| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "LD 1" |
| 58 |
.TH LD 1 2026-03-05 binutils-2.46 "GNU Development Tools" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
ld \- The GNU linker |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
ld [\fBoptions\fR] \fIobjfile\fR ... |
| 68 |
.SH DESCRIPTION |
| 69 |
.IX Header "DESCRIPTION" |
| 70 |
\&\fBld\fR combines a number of object and archive files, relocates |
| 71 |
their data and ties up symbol references. Usually the last step in |
| 72 |
compiling a program is to run \fBld\fR. |
| 73 |
.PP |
| 74 |
\&\fBld\fR accepts Linker Command Language files written in |
| 75 |
a superset of AT&T's Link Editor Command Language syntax, |
| 76 |
to provide explicit and total control over the linking process. |
| 77 |
.PP |
| 78 |
This man page does not describe the command language; see the |
| 79 |
\&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command |
| 80 |
language and on other aspects of the GNU linker. |
| 81 |
.PP |
| 82 |
This version of \fBld\fR uses the general purpose BFD libraries |
| 83 |
to operate on object files. This allows \fBld\fR to read, combine, and |
| 84 |
write object files in many different formats\-\-\-for example, COFF or |
| 85 |
\&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any |
| 86 |
available kind of object file. |
| 87 |
.PP |
| 88 |
Aside from its flexibility, the GNU linker is more helpful than other |
| 89 |
linkers in providing diagnostic information. Many linkers abandon |
| 90 |
execution immediately upon encountering an error; whenever possible, |
| 91 |
\&\fBld\fR continues executing, allowing you to identify other errors |
| 92 |
(or, in some cases, to get an output file in spite of the error). |
| 93 |
.PP |
| 94 |
The GNU linker \fBld\fR is meant to cover a broad range of situations, |
| 95 |
and to be as compatible as possible with other linkers. As a result, |
| 96 |
you have many choices to control its behavior. |
| 97 |
.SH OPTIONS |
| 98 |
.IX Header "OPTIONS" |
| 99 |
The linker supports a plethora of command-line options, but in actual |
| 100 |
practice few of them are used in any particular context. |
| 101 |
For instance, a frequent use of \fBld\fR is to link standard Unix |
| 102 |
object files on a standard, supported Unix system. On such a system, to |
| 103 |
link a file \f(CW\*(C`hello.o\*(C'\fR: |
| 104 |
.PP |
| 105 |
.Vb 1 |
| 106 |
\& ld \-o <output> /lib/crt0.o hello.o \-lc |
| 107 |
.Ve |
| 108 |
.PP |
| 109 |
This tells \fBld\fR to produce a file called \fIoutput\fR as the |
| 110 |
result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and |
| 111 |
the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search |
| 112 |
directories. (See the discussion of the \fB\-l\fR option below.) |
| 113 |
.PP |
| 114 |
Some of the command-line options to \fBld\fR may be specified at any |
| 115 |
point in the command line. However, options which refer to files, such |
| 116 |
as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at |
| 117 |
which the option appears in the command line, relative to the object |
| 118 |
files and other file options. Repeating non-file options with a |
| 119 |
different argument will either have no further effect, or override prior |
| 120 |
occurrences (those further to the left on the command line) of that |
| 121 |
option. Options which may be meaningfully specified more than once are |
| 122 |
noted in the descriptions below. |
| 123 |
.PP |
| 124 |
Non-option arguments are object files or archives which are to be linked |
| 125 |
together. They may follow, precede, or be mixed in with command-line |
| 126 |
options, except that an object file argument may not be placed between |
| 127 |
an option and its argument. |
| 128 |
.PP |
| 129 |
Usually the linker is invoked with at least one object file, but you can |
| 130 |
specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR, |
| 131 |
and the script command language. If \fIno\fR binary input files at all |
| 132 |
are specified, the linker does not produce any output, and issues the |
| 133 |
message \fBNo input files\fR. |
| 134 |
.PP |
| 135 |
If the linker cannot recognize the format of an object file, it will |
| 136 |
assume that it is a linker script. A script specified in this way |
| 137 |
augments the main linker script used for the link (either the default |
| 138 |
linker script or the one specified by using \fB\-T\fR). This feature |
| 139 |
permits the linker to link against a file which appears to be an object |
| 140 |
or an archive, but actually merely defines some symbol values, or uses |
| 141 |
\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Specifying a |
| 142 |
script in this way merely augments the main linker script, with the |
| 143 |
extra commands placed after the main script; use the \fB\-T\fR option |
| 144 |
to replace the default linker script entirely, but note the effect of |
| 145 |
the \f(CW\*(C`INSERT\*(C'\fR command. |
| 146 |
.PP |
| 147 |
For options whose names are a single letter, |
| 148 |
option arguments must either follow the option letter without intervening |
| 149 |
whitespace, or be given as separate arguments immediately following the |
| 150 |
option that requires them. |
| 151 |
.PP |
| 152 |
For options whose names are multiple letters, either one dash or two can |
| 153 |
precede the option name; for example, \fB\-trace\-symbol\fR and |
| 154 |
\&\fB\-\-trace\-symbol\fR are equivalent. Note\-\-\-there is one exception to |
| 155 |
this rule. Multiple letter options that start with a lower case 'o' can |
| 156 |
only be preceded by two dashes. This is to reduce confusion with the |
| 157 |
\&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file |
| 158 |
name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the NMAGIC flag on the |
| 159 |
output. |
| 160 |
.PP |
| 161 |
Arguments to multiple-letter options must either be separated from the |
| 162 |
option name by an equals sign, or be given as separate arguments |
| 163 |
immediately following the option that requires them. For example, |
| 164 |
\&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent. |
| 165 |
Unique abbreviations of the names of multiple-letter options are |
| 166 |
accepted. |
| 167 |
.PP |
| 168 |
Note\-\-\-if the linker is being invoked indirectly, via a compiler driver |
| 169 |
(e.g. \fBgcc\fR) then all the linker command-line options should be |
| 170 |
prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular |
| 171 |
compiler driver) like this: |
| 172 |
.PP |
| 173 |
.Vb 1 |
| 174 |
\& gcc \-Wl,\-\-start\-group foo.o bar.o \-Wl,\-\-end\-group |
| 175 |
.Ve |
| 176 |
.PP |
| 177 |
This is important, because otherwise the compiler driver program may |
| 178 |
silently drop the linker options, resulting in a bad link. Confusion |
| 179 |
may also arise when passing options that require values through a |
| 180 |
driver, as the use of a space between option and argument acts as |
| 181 |
a separator, and causes the driver to pass only the option to the linker |
| 182 |
and the argument to the compiler. In this case, it is simplest to use |
| 183 |
the joined forms of both single\- and multiple-letter options, such as: |
| 184 |
.PP |
| 185 |
.Vb 1 |
| 186 |
\& gcc foo.o bar.o \-Wl,\-eENTRY \-Wl,\-Map=a.map |
| 187 |
.Ve |
| 188 |
.PP |
| 189 |
Here is a table of the generic command-line switches accepted by the GNU |
| 190 |
linker: |
| 191 |
.IP \fB@\fR\fIfile\fR 4 |
| 192 |
.IX Item "@file" |
| 193 |
Read command-line options from \fIfile\fR. The options read are |
| 194 |
inserted in place of the original @\fIfile\fR option. If \fIfile\fR |
| 195 |
does not exist, or cannot be read, then the option will be treated |
| 196 |
literally, and not removed. |
| 197 |
.Sp |
| 198 |
Options in \fIfile\fR are separated by whitespace. A whitespace |
| 199 |
character may be included in an option by surrounding the entire |
| 200 |
option in either single or double quotes. Any character (including a |
| 201 |
backslash) may be included by prefixing the character to be included |
| 202 |
with a backslash. The \fIfile\fR may itself contain additional |
| 203 |
@\fIfile\fR options; any such options will be processed recursively. |
| 204 |
.IP "\fB\-a\fR \fIkeyword\fR" 4 |
| 205 |
.IX Item "-a keyword" |
| 206 |
This option is supported for HP/UX compatibility. The \fIkeyword\fR |
| 207 |
argument must be one of the strings \fBarchive\fR, \fBshared\fR, or |
| 208 |
\&\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to |
| 209 |
\&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent |
| 210 |
to \fB\-Bdynamic\fR. This option may be used any number of times. |
| 211 |
.IP "\fB\-\-audit\fR \fIAUDITLIB\fR" 4 |
| 212 |
.IX Item "--audit AUDITLIB" |
| 213 |
Adds \fIAUDITLIB\fR to the \f(CW\*(C`DT_AUDIT\*(C'\fR entry of the dynamic section. |
| 214 |
\&\fIAUDITLIB\fR is not checked for existence, nor will it use the DT_SONAME |
| 215 |
specified in the library. If specified multiple times \f(CW\*(C`DT_AUDIT\*(C'\fR |
| 216 |
will contain a colon separated list of audit interfaces to use. If the linker |
| 217 |
finds an object with an audit entry while searching for shared libraries, |
| 218 |
it will add a corresponding \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry in the output file. |
| 219 |
This option is only meaningful on ELF platforms supporting the rtld-audit |
| 220 |
interface. |
| 221 |
.IP "\fB\-b\fR \fIinput-format\fR" 4 |
| 222 |
.IX Item "-b input-format" |
| 223 |
.PD 0 |
| 224 |
.IP \fB\-\-format=\fR\fIinput-format\fR 4 |
| 225 |
.IX Item "--format=input-format" |
| 226 |
.PD |
| 227 |
\&\fBld\fR may be configured to support more than one kind of object |
| 228 |
file. If your \fBld\fR is configured this way, you can use the |
| 229 |
\&\fB\-b\fR option to specify the binary format for input object files |
| 230 |
that follow this option on the command line. Even when \fBld\fR is |
| 231 |
configured to support alternative object formats, you don't usually need |
| 232 |
to specify this, as \fBld\fR should be configured to expect as a |
| 233 |
default input format the most usual format on each machine. |
| 234 |
\&\fIinput-format\fR is a text string, the name of a particular format |
| 235 |
supported by the BFD libraries. (You can list the available binary |
| 236 |
formats with \fBobjdump \-i\fR.) |
| 237 |
.Sp |
| 238 |
You may want to use this option if you are linking files with an unusual |
| 239 |
binary format. You can also use \fB\-b\fR to switch formats explicitly (when |
| 240 |
linking object files of different formats), by including |
| 241 |
\&\fB\-b\fR \fIinput-format\fR before each group of object files in a |
| 242 |
particular format. |
| 243 |
.Sp |
| 244 |
The default format is taken from the environment variable |
| 245 |
\&\f(CW\*(C`GNUTARGET\*(C'\fR. |
| 246 |
.Sp |
| 247 |
You can also define the input format from a script, using the command |
| 248 |
\&\f(CW\*(C`TARGET\*(C'\fR; |
| 249 |
.IP "\fB\-c\fR \fIMRI-commandfile\fR" 4 |
| 250 |
.IX Item "-c MRI-commandfile" |
| 251 |
.PD 0 |
| 252 |
.IP \fB\-\-mri\-script=\fR\fIMRI-commandfile\fR 4 |
| 253 |
.IX Item "--mri-script=MRI-commandfile" |
| 254 |
.PD |
| 255 |
For compatibility with linkers produced by MRI, \fBld\fR accepts script |
| 256 |
files written in an alternate, restricted command language, described in |
| 257 |
the MRI Compatible Script Files section of GNU ld documentation. |
| 258 |
Introduce MRI script files with |
| 259 |
the option \fB\-c\fR; use the \fB\-T\fR option to run linker |
| 260 |
scripts written in the general-purpose \fBld\fR scripting language. |
| 261 |
If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories |
| 262 |
specified by any \fB\-L\fR options. |
| 263 |
.IP \fB\-d\fR 4 |
| 264 |
.IX Item "-d" |
| 265 |
.PD 0 |
| 266 |
.IP \fB\-dc\fR 4 |
| 267 |
.IX Item "-dc" |
| 268 |
.IP \fB\-dp\fR 4 |
| 269 |
.IX Item "-dp" |
| 270 |
.PD |
| 271 |
These three options are equivalent; multiple forms are supported for |
| 272 |
compatibility with other linkers. They assign space to common symbols |
| 273 |
even if a relocatable output file is specified (with \fB\-r\fR). The |
| 274 |
script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect. |
| 275 |
.IP "\fB\-\-depaudit\fR \fIAUDITLIB\fR" 4 |
| 276 |
.IX Item "--depaudit AUDITLIB" |
| 277 |
.PD 0 |
| 278 |
.IP "\fB\-P\fR \fIAUDITLIB\fR" 4 |
| 279 |
.IX Item "-P AUDITLIB" |
| 280 |
.PD |
| 281 |
Adds \fIAUDITLIB\fR to the \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry of the dynamic section. |
| 282 |
\&\fIAUDITLIB\fR is not checked for existence, nor will it use the DT_SONAME |
| 283 |
specified in the library. If specified multiple times \f(CW\*(C`DT_DEPAUDIT\*(C'\fR |
| 284 |
will contain a colon separated list of audit interfaces to use. This |
| 285 |
option is only meaningful on ELF platforms supporting the rtld-audit interface. |
| 286 |
The \-P option is provided for Solaris compatibility. |
| 287 |
.IP \fB\-\-enable\-linker\-version\fR 4 |
| 288 |
.IX Item "--enable-linker-version" |
| 289 |
Enables the \f(CW\*(C`LINKER_VERSION\*(C'\fR linker script directive, described |
| 290 |
in \fBOutput Section Data\fR. If this directive is used in a linker |
| 291 |
script and this option has been enabled then a string containing the |
| 292 |
linker version will be inserted at the current point. |
| 293 |
.Sp |
| 294 |
Note \- this location of this option on the linker command line is |
| 295 |
significant. It will only affect linker scripts that come after it on |
| 296 |
the command line, or which are built into the linker. |
| 297 |
.IP \fB\-\-disable\-linker\-version\fR 4 |
| 298 |
.IX Item "--disable-linker-version" |
| 299 |
Disables the \f(CW\*(C`LINKER_VERSION\*(C'\fR linker script directive, so that it |
| 300 |
does not insert a version string. This is the default. |
| 301 |
.IP \fB\-\-enable\-non\-contiguous\-regions\fR 4 |
| 302 |
.IX Item "--enable-non-contiguous-regions" |
| 303 |
This option avoids generating an error if an input section does not |
| 304 |
fit a matching output section. The linker tries to allocate the input |
| 305 |
section to subseque nt matching output sections, and generates an |
| 306 |
error only if no output section is large enough. This is useful when |
| 307 |
several non-contiguous memory regions are available and the input |
| 308 |
section does not require a particular one. The order in which input |
| 309 |
sections are evaluated does not change, for instance: |
| 310 |
.Sp |
| 311 |
.Vb 10 |
| 312 |
\& MEMORY { |
| 313 |
\& MEM1 (rwx) : ORIGIN = 0x1000, LENGTH = 0x14 |
| 314 |
\& MEM2 (rwx) : ORIGIN = 0x1000, LENGTH = 0x40 |
| 315 |
\& MEM3 (rwx) : ORIGIN = 0x2000, LENGTH = 0x40 |
| 316 |
\& } |
| 317 |
\& SECTIONS { |
| 318 |
\& mem1 : { *(.data.*); } > MEM1 |
| 319 |
\& mem2 : { *(.data.*); } > MEM2 |
| 320 |
\& mem3 : { *(.data.*); } > MEM3 |
| 321 |
\& } |
| 322 |
\& |
| 323 |
\& with input sections: |
| 324 |
\& .data.1: size 8 |
| 325 |
\& .data.2: size 0x10 |
| 326 |
\& .data.3: size 4 |
| 327 |
\& |
| 328 |
\& results in .data.1 affected to mem1, and .data.2 and .data.3 |
| 329 |
\& affected to mem2, even though .data.3 would fit in mem3. |
| 330 |
.Ve |
| 331 |
.Sp |
| 332 |
This option is incompatible with INSERT statements because it changes |
| 333 |
the way input sections are mapped to output sections. |
| 334 |
.IP \fB\-\-enable\-non\-contiguous\-regions\-warnings\fR 4 |
| 335 |
.IX Item "--enable-non-contiguous-regions-warnings" |
| 336 |
This option enables warnings when |
| 337 |
\&\f(CW\*(C`\-\-enable\-non\-contiguous\-regions\*(C'\fR allows possibly unexpected |
| 338 |
matches in sections mapping, potentially leading to silently |
| 339 |
discarding a section instead of failing because it does not fit any |
| 340 |
output region. |
| 341 |
.IP "\fB\-e\fR \fIentry\fR" 4 |
| 342 |
.IX Item "-e entry" |
| 343 |
.PD 0 |
| 344 |
.IP \fB\-\-entry=\fR\fIentry\fR 4 |
| 345 |
.IX Item "--entry=entry" |
| 346 |
.PD |
| 347 |
Use \fIentry\fR as the explicit symbol for beginning execution of your |
| 348 |
program, rather than the default entry point. If there is no symbol |
| 349 |
named \fIentry\fR, the linker will try to parse \fIentry\fR as a number, |
| 350 |
and use that as the entry address (the number will be interpreted in |
| 351 |
base 10; you may use a leading \fB0x\fR for base 16, or a leading |
| 352 |
\&\fB0\fR for base 8). For i386 PE, \fIentry\fR |
| 353 |
can be also the original function name (without the leading underscore |
| 354 |
and/or the trailing stdcall \fR\f(CB@number\fR\fB\fR when applicable). |
| 355 |
.IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4 |
| 356 |
.IX Item "--exclude-libs lib,lib,..." |
| 357 |
Specifies a list of archive libraries from which symbols should not be automatically |
| 358 |
exported. The library names may be delimited by commas or colons. Specifying |
| 359 |
\&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from |
| 360 |
automatic export. This option is available only for the i386 PE targeted |
| 361 |
port of the linker and for ELF targeted ports. For i386 PE, symbols |
| 362 |
explicitly listed in a .def file are still exported, regardless of this |
| 363 |
option. For ELF targeted ports, symbols affected by this option will |
| 364 |
be treated as hidden. |
| 365 |
.IP "\fB\-\-exclude\-modules\-for\-implib\fR \fImodule\fR\fB,\fR\fImodule\fR\fB,...\fR" 4 |
| 366 |
.IX Item "--exclude-modules-for-implib module,module,..." |
| 367 |
Specifies a list of object files or archive members, from which symbols |
| 368 |
should not be automatically exported, but which should be copied wholesale |
| 369 |
into the import library being generated during the link. The module names |
| 370 |
may be delimited by commas or colons, and must match exactly the filenames |
| 371 |
used by \fBld\fR to open the files; for archive members, this is simply |
| 372 |
the member name, but for object files the name listed must include and |
| 373 |
match precisely any path used to specify the input file on the linker's |
| 374 |
command-line. This option is available only for the i386 PE targeted port |
| 375 |
of the linker. Symbols explicitly listed in a .def file are still exported, |
| 376 |
regardless of this option. |
| 377 |
.IP \fB\-E\fR 4 |
| 378 |
.IX Item "-E" |
| 379 |
.PD 0 |
| 380 |
.IP \fB\-\-export\-dynamic\fR 4 |
| 381 |
.IX Item "--export-dynamic" |
| 382 |
.IP \fB\-\-no\-export\-dynamic\fR 4 |
| 383 |
.IX Item "--no-export-dynamic" |
| 384 |
.PD |
| 385 |
When creating a dynamically linked executable, using the \fB\-E\fR |
| 386 |
option or the \fB\-\-export\-dynamic\fR option causes the linker to add |
| 387 |
all symbols to the dynamic symbol table. The dynamic symbol table is the |
| 388 |
set of symbols which are visible from dynamic objects at run time. |
| 389 |
.Sp |
| 390 |
If you do not use either of these options (or use the |
| 391 |
\&\fB\-\-no\-export\-dynamic\fR option to restore the default behavior), the |
| 392 |
dynamic symbol table will normally contain only those symbols which are |
| 393 |
referenced by some dynamic object mentioned in the link. |
| 394 |
.Sp |
| 395 |
If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer |
| 396 |
back to the symbols defined by the program, rather than some other |
| 397 |
dynamic object, then you will probably need to use this option when |
| 398 |
linking the program itself. |
| 399 |
.Sp |
| 400 |
You can also use the dynamic list to control what symbols should |
| 401 |
be added to the dynamic symbol table if the output format supports it. |
| 402 |
See the description of \fB\-\-dynamic\-list\fR. |
| 403 |
.Sp |
| 404 |
Note that this option is specific to ELF targeted ports. PE targets |
| 405 |
support a similar function to export all symbols from a DLL or EXE; see |
| 406 |
the description of \fB\-\-export\-all\-symbols\fR below. |
| 407 |
.IP \fB\-\-export\-dynamic\-symbol=\fR\fIglob\fR 4 |
| 408 |
.IX Item "--export-dynamic-symbol=glob" |
| 409 |
When creating a dynamically linked executable, symbols matching |
| 410 |
\&\fIglob\fR will be added to the dynamic symbol table. When creating a |
| 411 |
shared library, references to symbols matching \fIglob\fR will not be |
| 412 |
bound to the definitions within the shared library. This option is a |
| 413 |
no-op when creating a shared library and \fB\-Bsymbolic\fR or |
| 414 |
\&\fB\-\-dynamic\-list\fR are not specified. This option is only meaningful |
| 415 |
on ELF platforms which support shared libraries. |
| 416 |
.IP \fB\-\-export\-dynamic\-symbol\-list=\fR\fIfile\fR 4 |
| 417 |
.IX Item "--export-dynamic-symbol-list=file" |
| 418 |
Specify a \fB\-\-export\-dynamic\-symbol\fR for each pattern in the file. |
| 419 |
The format of the file is the same as the version node without |
| 420 |
scope and node name. See \fBVERSION\fR for more information. |
| 421 |
.IP \fB\-EB\fR 4 |
| 422 |
.IX Item "-EB" |
| 423 |
Link big-endian objects. This affects the default output format. |
| 424 |
.IP \fB\-EL\fR 4 |
| 425 |
.IX Item "-EL" |
| 426 |
Link little-endian objects. This affects the default output format. |
| 427 |
.IP "\fB\-f\fR \fIname\fR" 4 |
| 428 |
.IX Item "-f name" |
| 429 |
.PD 0 |
| 430 |
.IP \fB\-\-auxiliary=\fR\fIname\fR 4 |
| 431 |
.IX Item "--auxiliary=name" |
| 432 |
.PD |
| 433 |
When creating an ELF shared object, set the internal DT_AUXILIARY field |
| 434 |
to the specified name. This tells the dynamic linker that the symbol |
| 435 |
table of the shared object should be used as an auxiliary filter on the |
| 436 |
symbol table of the shared object \fIname\fR. |
| 437 |
.Sp |
| 438 |
If you later link a program against this filter object, then, when you |
| 439 |
run the program, the dynamic linker will see the DT_AUXILIARY field. If |
| 440 |
the dynamic linker resolves any symbols from the filter object, it will |
| 441 |
first check whether there is a definition in the shared object |
| 442 |
\&\fIname\fR. If there is one, it will be used instead of the definition |
| 443 |
in the filter object. The shared object \fIname\fR need not exist. |
| 444 |
Thus the shared object \fIname\fR may be used to provide an alternative |
| 445 |
implementation of certain functions, perhaps for debugging or for |
| 446 |
machine-specific performance. |
| 447 |
.Sp |
| 448 |
This option may be specified more than once. The DT_AUXILIARY entries |
| 449 |
will be created in the order in which they appear on the command line. |
| 450 |
.IP "\fB\-F\fR \fIname\fR" 4 |
| 451 |
.IX Item "-F name" |
| 452 |
.PD 0 |
| 453 |
.IP \fB\-\-filter=\fR\fIname\fR 4 |
| 454 |
.IX Item "--filter=name" |
| 455 |
.PD |
| 456 |
When creating an ELF shared object, set the internal DT_FILTER field to |
| 457 |
the specified name. This tells the dynamic linker that the symbol table |
| 458 |
of the shared object which is being created should be used as a filter |
| 459 |
on the symbol table of the shared object \fIname\fR. |
| 460 |
.Sp |
| 461 |
If you later link a program against this filter object, then, when you |
| 462 |
run the program, the dynamic linker will see the DT_FILTER field. The |
| 463 |
dynamic linker will resolve symbols according to the symbol table of the |
| 464 |
filter object as usual, but it will actually link to the definitions |
| 465 |
found in the shared object \fIname\fR. Thus the filter object can be |
| 466 |
used to select a subset of the symbols provided by the object |
| 467 |
\&\fIname\fR. |
| 468 |
.Sp |
| 469 |
Some older linkers used the \fB\-F\fR option throughout a compilation |
| 470 |
toolchain for specifying object-file format for both input and output |
| 471 |
object files. |
| 472 |
The GNU linker uses other mechanisms for this purpose: the |
| 473 |
\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the |
| 474 |
\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR |
| 475 |
environment variable. |
| 476 |
The GNU linker will ignore the \fB\-F\fR option when not |
| 477 |
creating an ELF shared object. |
| 478 |
.IP \fB\-fini=\fR\fIname\fR 4 |
| 479 |
.IX Item "-fini=name" |
| 480 |
When creating an ELF executable or shared object, call NAME when the |
| 481 |
executable or shared object is unloaded, by setting DT_FINI to the |
| 482 |
address of the function. By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as |
| 483 |
the function to call. |
| 484 |
.IP \fB\-g\fR 4 |
| 485 |
.IX Item "-g" |
| 486 |
Ignored. Provided for compatibility with other tools. |
| 487 |
.IP "\fB\-G\fR \fIvalue\fR" 4 |
| 488 |
.IX Item "-G value" |
| 489 |
.PD 0 |
| 490 |
.IP \fB\-\-gpsize=\fR\fIvalue\fR 4 |
| 491 |
.IX Item "--gpsize=value" |
| 492 |
.PD |
| 493 |
Set the maximum size of objects to be optimized using the GP register to |
| 494 |
\&\fIsize\fR. This is only meaningful for object file formats such as |
| 495 |
MIPS ELF that support putting large and small objects into different |
| 496 |
sections. This is ignored for other object file formats. |
| 497 |
.IP "\fB\-h\fR \fIname\fR" 4 |
| 498 |
.IX Item "-h name" |
| 499 |
.PD 0 |
| 500 |
.IP \fB\-soname=\fR\fIname\fR 4 |
| 501 |
.IX Item "-soname=name" |
| 502 |
.PD |
| 503 |
When creating an ELF shared object, set the internal DT_SONAME field to |
| 504 |
the specified name. When an executable is linked with a shared object |
| 505 |
which has a DT_SONAME field, then when the executable is run the dynamic |
| 506 |
linker will attempt to load the shared object specified by the DT_SONAME |
| 507 |
field rather than using the file name given to the linker. |
| 508 |
.IP \fB\-i\fR 4 |
| 509 |
.IX Item "-i" |
| 510 |
Perform an incremental link (same as option \fB\-r\fR). |
| 511 |
.IP \fB\-init=\fR\fIname\fR 4 |
| 512 |
.IX Item "-init=name" |
| 513 |
When creating an ELF executable or shared object, call NAME when the |
| 514 |
executable or shared object is loaded, by setting DT_INIT to the address |
| 515 |
of the function. By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the |
| 516 |
function to call. |
| 517 |
.IP "\fB\-l\fR \fInamespec\fR" 4 |
| 518 |
.IX Item "-l namespec" |
| 519 |
.PD 0 |
| 520 |
.IP \fB\-\-library=\fR\fInamespec\fR 4 |
| 521 |
.IX Item "--library=namespec" |
| 522 |
.PD |
| 523 |
Add the archive or object file specified by \fInamespec\fR to the |
| 524 |
list of files to link. This option may be used any number of times. |
| 525 |
If \fInamespec\fR is of the form \fI:filename\fR, \fBld\fR |
| 526 |
will search the library path for a file called \fIfilename\fR, otherwise it |
| 527 |
will search the library path for a file called \fIlibnamespec.a\fR. |
| 528 |
.Sp |
| 529 |
On systems which support shared libraries, \fBld\fR may also search for |
| 530 |
files other than \fIlibnamespec.a\fR. Specifically, on ELF |
| 531 |
and SunOS systems, \fBld\fR will search a directory for a library |
| 532 |
called \fIlibnamespec.so\fR before searching for one called |
| 533 |
\&\fIlibnamespec.a\fR. (By convention, a \f(CW\*(C`.so\*(C'\fR extension |
| 534 |
indicates a shared library.) Note that this behavior does not apply |
| 535 |
to \fI:filename\fR, which always specifies a file called |
| 536 |
\&\fIfilename\fR. |
| 537 |
.Sp |
| 538 |
The linker will search an archive only once, at the location where it is |
| 539 |
specified on the command line. If the archive defines a symbol which |
| 540 |
was undefined in some object which appeared before the archive on the |
| 541 |
command line, the linker will include the appropriate file(s) from the |
| 542 |
archive. However, an undefined symbol in an object appearing later on |
| 543 |
the command line will not cause the linker to search the archive again. |
| 544 |
.Sp |
| 545 |
See the \fB\-(\fR option for a way to force the linker to search |
| 546 |
archives multiple times. |
| 547 |
.Sp |
| 548 |
You may list the same archive multiple times on the command line. |
| 549 |
.Sp |
| 550 |
This type of archive searching is standard for Unix linkers. However, |
| 551 |
if you are using \fBld\fR on AIX, note that it is different from the |
| 552 |
behaviour of the AIX linker. |
| 553 |
.IP "\fB\-L\fR \fIsearchdir\fR" 4 |
| 554 |
.IX Item "-L searchdir" |
| 555 |
.PD 0 |
| 556 |
.IP \fB\-\-library\-path=\fR\fIsearchdir\fR 4 |
| 557 |
.IX Item "--library-path=searchdir" |
| 558 |
.PD |
| 559 |
Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search |
| 560 |
for archive libraries and \fBld\fR control scripts. You may use this |
| 561 |
option any number of times. The directories are searched in the order |
| 562 |
in which they are specified on the command line. Directories specified |
| 563 |
on the command line are searched before the default directories. All |
| 564 |
\&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the |
| 565 |
order in which the options appear. \fB\-L\fR options do not affect |
| 566 |
how \fBld\fR searches for a linker script unless \fB\-T\fR |
| 567 |
option is specified. |
| 568 |
.Sp |
| 569 |
If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR or \f(CW$SYSROOT\fR, then this |
| 570 |
prefix will be replaced by the \fIsysroot prefix\fR, controlled by the |
| 571 |
\&\fB\-\-sysroot\fR option, or specified when the linker is configured. |
| 572 |
.Sp |
| 573 |
The default set of paths searched (without being specified with |
| 574 |
\&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in |
| 575 |
some cases also on how it was configured. |
| 576 |
.Sp |
| 577 |
The paths can also be specified in a link script with the |
| 578 |
\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched |
| 579 |
at the point in which the linker script appears in the command line. |
| 580 |
.IP "\fB\-m\fR \fIemulation\fR" 4 |
| 581 |
.IX Item "-m emulation" |
| 582 |
Emulate the \fIemulation\fR linker. You can list the available |
| 583 |
emulations with the \fB\-\-verbose\fR or \fB\-V\fR options. |
| 584 |
.Sp |
| 585 |
If the \fB\-m\fR option is not used, the emulation is taken from the |
| 586 |
\&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined. |
| 587 |
.Sp |
| 588 |
Otherwise, the default emulation depends upon how the linker was |
| 589 |
configured. |
| 590 |
.IP \fB\-\-remap\-inputs=\fR\f(BIpattern\fR\fB=\fR\f(BIfilename\fR 4 |
| 591 |
.IX Item "--remap-inputs=pattern=filename" |
| 592 |
.PD 0 |
| 593 |
.IP \fB\-\-remap\-inputs\-file=\fR\f(BIfile\fR 4 |
| 594 |
.IX Item "--remap-inputs-file=file" |
| 595 |
.PD |
| 596 |
These options allow the names of input files to be changed before the |
| 597 |
linker attempts to open them. The option |
| 598 |
\&\fB\-\-remap\-inputs=foo.o=bar.o\fR will cause any attempt to load a |
| 599 |
file called \fIfoo.o\fR to instead try to load a file called |
| 600 |
\&\fIbar.o\fR. Wildcard patterns are permitted in the first filename, |
| 601 |
so \fB\-\-remap\-inputs=foo*.o=bar.o\fR will rename any input file that |
| 602 |
matches \fIfoo*.o\fR to \fIbar.o\fR. |
| 603 |
.Sp |
| 604 |
An alternative form of the option |
| 605 |
\&\fB\-\-remap\-inputs\-file=filename\fR allows the remappings to be read |
| 606 |
from a file. Each line in the file can contain a single remapping. |
| 607 |
Blank lines are ignored. Anything from a hash character (\fB#\fR) to |
| 608 |
the end of a line is considered to be a comment and is also ignored. |
| 609 |
The mapping pattern can be separated from the filename by whitespace |
| 610 |
or an equals (\fB=\fR) character. |
| 611 |
.Sp |
| 612 |
The options can be specified multiple times. Their contents |
| 613 |
accumulate. The remappings will be processed in the order in which |
| 614 |
they occur on the command line, and if they come from a file, in the |
| 615 |
order in which they occur in the file. If a match is made, no further |
| 616 |
checking for that filename will be performed. |
| 617 |
.Sp |
| 618 |
If the replacement filename is \fI/dev/null\fR or just \fINUL\fR |
| 619 |
then the remapping will actually cause the input file to be ignored. |
| 620 |
This can be a convenient way to experiment with removing input files |
| 621 |
from a complicated build environment. |
| 622 |
.Sp |
| 623 |
Note that this option is position dependent and only affects filenames |
| 624 |
that come after it on the command line. Thus: |
| 625 |
.Sp |
| 626 |
.Vb 1 |
| 627 |
\& ld foo.o \-\-remap\-inputs=foo.o=bar.o |
| 628 |
.Ve |
| 629 |
.Sp |
| 630 |
Will have no effect, whereas: |
| 631 |
.Sp |
| 632 |
.Vb 1 |
| 633 |
\& ld \-\-remap\-inputs=foo.o=bar.o foo.o |
| 634 |
.Ve |
| 635 |
.Sp |
| 636 |
Will rename the input file \fIfoo.o\fR to \fIbar.o\fR. |
| 637 |
.Sp |
| 638 |
Note \- these options also affect files referenced by \fIINPUT\fR |
| 639 |
statements in linker scripts. But since linker scripts are processed |
| 640 |
after the entire command line is read, the position of the remap |
| 641 |
options on the command line is not significant. |
| 642 |
.Sp |
| 643 |
If the \fBverbose\fR option is enabled then any mappings that match |
| 644 |
will be reported, although again the \fBverbose\fR option needs to |
| 645 |
be enabled on the command line \fIbefore\fR the remaped filenames |
| 646 |
appear. |
| 647 |
.Sp |
| 648 |
If the \fB\-Map\fR or \fB\-\-print\-map\fR options are enabled then |
| 649 |
the remapping list will be included in the map output. |
| 650 |
.IP \fB\-M\fR 4 |
| 651 |
.IX Item "-M" |
| 652 |
.PD 0 |
| 653 |
.IP \fB\-\-print\-map\fR 4 |
| 654 |
.IX Item "--print-map" |
| 655 |
.PD |
| 656 |
Print a link map to the standard output. A link map provides |
| 657 |
information about the link, including the following: |
| 658 |
.RS 4 |
| 659 |
.IP \(bu 4 |
| 660 |
Where object files are mapped into memory. |
| 661 |
.IP \(bu 4 |
| 662 |
How common symbols are allocated. |
| 663 |
.IP \(bu 4 |
| 664 |
All archive members included in the link, with a mention of the symbol |
| 665 |
which caused the archive member to be brought in. |
| 666 |
.IP \(bu 4 |
| 667 |
The values assigned to symbols. |
| 668 |
.Sp |
| 669 |
Note \- symbols whose values are computed by an expression which |
| 670 |
involves a reference to a previous value of the same symbol may not |
| 671 |
have correct result displayed in the link map. This is because the |
| 672 |
linker discards intermediate results and only retains the final value |
| 673 |
of an expression. Under such circumstances the linker will display |
| 674 |
the final value enclosed by square brackets. Thus for example a |
| 675 |
linker script containing: |
| 676 |
.Sp |
| 677 |
.Vb 3 |
| 678 |
\& foo = 1 |
| 679 |
\& foo = foo * 4 |
| 680 |
\& foo = foo + 8 |
| 681 |
.Ve |
| 682 |
.Sp |
| 683 |
will produce the following output in the link map if the \fB\-M\fR |
| 684 |
option is used: |
| 685 |
.Sp |
| 686 |
.Vb 3 |
| 687 |
\& 0x00000001 foo = 0x1 |
| 688 |
\& [0x0000000c] foo = (foo * 0x4) |
| 689 |
\& [0x0000000c] foo = (foo + 0x8) |
| 690 |
.Ve |
| 691 |
.Sp |
| 692 |
See \fBExpressions\fR for more information about expressions in linker |
| 693 |
scripts. |
| 694 |
.IP \(bu 4 |
| 695 |
How GNU properties are merged. |
| 696 |
.Sp |
| 697 |
When the linker merges input .note.gnu.property sections into one output |
| 698 |
\&.note.gnu.property section, some properties are removed or updated. |
| 699 |
These actions are reported in the link map. For example: |
| 700 |
.Sp |
| 701 |
.Vb 1 |
| 702 |
\& Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found) |
| 703 |
.Ve |
| 704 |
.Sp |
| 705 |
This indicates that property 0xc0000002 is removed from output when |
| 706 |
merging properties in \fIfoo.o\fR, whose property 0xc0000002 value |
| 707 |
is 0x1, and \fIbar.o\fR, which doesn't have property 0xc0000002. |
| 708 |
.Sp |
| 709 |
.Vb 1 |
| 710 |
\& Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1) |
| 711 |
.Ve |
| 712 |
.Sp |
| 713 |
This indicates that property 0xc0010001 value is updated to 0x1 in output |
| 714 |
when merging properties in \fIfoo.o\fR, whose 0xc0010001 property value |
| 715 |
is 0x1, and \fIbar.o\fR, whose 0xc0010001 property value is 0x1. |
| 716 |
.IP \(bu 4 |
| 717 |
On some ELF targets, a list of fixups inserted by \fB\-\-relax\fR |
| 718 |
.Sp |
| 719 |
.Vb 1 |
| 720 |
\& foo.o: Adjusting branch at 0x00000008 towards "far" in section .text |
| 721 |
.Ve |
| 722 |
.Sp |
| 723 |
This indicates that the branch at 0x00000008 in foo.o, targeting |
| 724 |
the symbol "far" in section .text, has been replaced by a trampoline. |
| 725 |
.RE |
| 726 |
.RS 4 |
| 727 |
.RE |
| 728 |
.IP \fB\-\-print\-map\-discarded\fR 4 |
| 729 |
.IX Item "--print-map-discarded" |
| 730 |
.PD 0 |
| 731 |
.IP \fB\-\-no\-print\-map\-discarded\fR 4 |
| 732 |
.IX Item "--no-print-map-discarded" |
| 733 |
.PD |
| 734 |
Print (or do not print) the list of discarded and garbage collected sections |
| 735 |
in the link map. Enabled by default. |
| 736 |
.IP \fB\-\-print\-map\-locals\fR 4 |
| 737 |
.IX Item "--print-map-locals" |
| 738 |
.PD 0 |
| 739 |
.IP \fB\-\-no\-print\-map\-locals\fR 4 |
| 740 |
.IX Item "--no-print-map-locals" |
| 741 |
.PD |
| 742 |
Print (or do not print) local symbols in the link map. Local symbols |
| 743 |
will have the text \fB(local)\fR printed before their name, and will |
| 744 |
be listed after all of the global symbols in a given section. |
| 745 |
Temporary local symbols (typically those that start with \fB.L\fR) |
| 746 |
will not be included in the output. Disabled by default. |
| 747 |
.IP \fB\-n\fR 4 |
| 748 |
.IX Item "-n" |
| 749 |
.PD 0 |
| 750 |
.IP \fB\-\-nmagic\fR 4 |
| 751 |
.IX Item "--nmagic" |
| 752 |
.PD |
| 753 |
Turn off page alignment of sections, and disable linking against shared |
| 754 |
libraries. If the output format supports Unix style magic numbers, |
| 755 |
mark the output as \f(CW\*(C`NMAGIC\*(C'\fR. |
| 756 |
.IP \fB\-N\fR 4 |
| 757 |
.IX Item "-N" |
| 758 |
.PD 0 |
| 759 |
.IP \fB\-\-omagic\fR 4 |
| 760 |
.IX Item "--omagic" |
| 761 |
.PD |
| 762 |
Set the text and data sections to be readable and writable. Also, do |
| 763 |
not page-align the data segment, and disable linking against shared |
| 764 |
libraries. If the output format supports Unix style magic numbers, |
| 765 |
mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section |
| 766 |
is allowed for PE-COFF targets, it does not conform to the format |
| 767 |
specification published by Microsoft. |
| 768 |
.IP \fB\-\-no\-omagic\fR 4 |
| 769 |
.IX Item "--no-omagic" |
| 770 |
This option negates most of the effects of the \fB\-N\fR option. It |
| 771 |
sets the text section to be read-only, and forces the data segment to |
| 772 |
be page-aligned. Note \- this option does not enable linking against |
| 773 |
shared libraries. Use \fB\-Bdynamic\fR for this. |
| 774 |
.IP "\fB\-o\fR \fIoutput\fR" 4 |
| 775 |
.IX Item "-o output" |
| 776 |
.PD 0 |
| 777 |
.IP \fB\-\-output=\fR\fIoutput\fR 4 |
| 778 |
.IX Item "--output=output" |
| 779 |
.PD |
| 780 |
Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this |
| 781 |
option is not specified, the name \fIa.out\fR is used by default. The |
| 782 |
script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name. |
| 783 |
.Sp |
| 784 |
Note \- the linker will delete the output file before it starts to |
| 785 |
write to it. It will do this even if it turns out that the link |
| 786 |
cannot be completed due to errors. |
| 787 |
.Sp |
| 788 |
Note \- the linker will check to make sure that the output file name |
| 789 |
does not match the name of any of the input files, but that is all. |
| 790 |
In particular it will not complain if the output file might overwrite |
| 791 |
a source file or some other important file. Therefore in build |
| 792 |
systems it is recommended to use the \fB\-o\fR option as the last |
| 793 |
option on the linker command line. For example consider: |
| 794 |
.Sp |
| 795 |
.Vb 2 |
| 796 |
\& ld \-o $(EXE) $(OBJS) |
| 797 |
\& ld $(OBJS) \-o $(EXE) |
| 798 |
.Ve |
| 799 |
.Sp |
| 800 |
If the \fBEXE\fR variable is not defined for some reason, the first |
| 801 |
version of the linker command could end up deleting one of the object |
| 802 |
files (the first one in the \fBOBJS\fR list) whereas the second |
| 803 |
version of the linker command will generate an error message and not |
| 804 |
delete anything. |
| 805 |
.IP \fB\-\-dependency\-file=\fR\fIdepfile\fR 4 |
| 806 |
.IX Item "--dependency-file=depfile" |
| 807 |
Write a \fIdependency file\fR to \fIdepfile\fR. This file contains a rule |
| 808 |
suitable for \f(CW\*(C`make\*(C'\fR describing the output file and all the input files |
| 809 |
that were read to produce it. The output is similar to the compiler's |
| 810 |
output with \fB\-M \-MP\fR. Note that there is no option like the compiler's \fB\-MM\fR, |
| 811 |
to exclude "system files" (which is not a well-specified concept in the |
| 812 |
linker, unlike "system headers" in the compiler). So the output from |
| 813 |
\&\fB\-\-dependency\-file\fR is always specific to the exact state of the |
| 814 |
installation where it was produced, and should not be copied into |
| 815 |
distributed makefiles without careful editing. |
| 816 |
.IP "\fB\-O\fR \fIlevel\fR" 4 |
| 817 |
.IX Item "-O level" |
| 818 |
If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes |
| 819 |
the output. This might take significantly longer and therefore probably |
| 820 |
should only be enabled for the final binary. At the moment this |
| 821 |
option only affects ELF shared library generation. Future releases of |
| 822 |
the linker may make more use of this option. Also currently there is |
| 823 |
no difference in the linker's behaviour for different non-zero values |
| 824 |
of this option. Again this may change with future releases. |
| 825 |
.IP "\fB\-plugin\fR \fIname\fR" 4 |
| 826 |
.IX Item "-plugin name" |
| 827 |
Involve a plugin in the linking process. The \fIname\fR parameter is |
| 828 |
the absolute filename of the plugin. Usually this parameter is |
| 829 |
automatically added by the complier, when using link time |
| 830 |
optimization, but users can also add their own plugins if they so |
| 831 |
wish. |
| 832 |
.Sp |
| 833 |
Note that the location of the compiler originated plugins is different |
| 834 |
from the place where the \fBar\fR, \fBnm\fR and |
| 835 |
\&\fBranlib\fR programs search for their plugins. In order for |
| 836 |
those commands to make use of a compiler based plugin it must first be |
| 837 |
copied into the \fI${libdir}/bfd\-plugins\fR directory. All gcc |
| 838 |
based linker plugins are backward compatible, so it is sufficient to |
| 839 |
just copy in the newest one. |
| 840 |
.IP \fB\-\-push\-state\fR 4 |
| 841 |
.IX Item "--push-state" |
| 842 |
The \fB\-\-push\-state\fR allows one to preserve the current state of the |
| 843 |
flags which govern the input file handling so that they can all be |
| 844 |
restored with one corresponding \fB\-\-pop\-state\fR option. |
| 845 |
.Sp |
| 846 |
The option which are covered are: \fB\-Bdynamic\fR, \fB\-Bstatic\fR, |
| 847 |
\&\fB\-dn\fR, \fB\-dy\fR, \fB\-call_shared\fR, \fB\-non_shared\fR, |
| 848 |
\&\fB\-static\fR, \fB\-N\fR, \fB\-n\fR, \fB\-\-whole\-archive\fR, |
| 849 |
\&\fB\-\-no\-whole\-archive\fR, \fB\-r\fR, \fB\-Ur\fR, |
| 850 |
\&\fB\-\-copy\-dt\-needed\-entries\fR, \fB\-\-no\-copy\-dt\-needed\-entries\fR, |
| 851 |
\&\fB\-\-as\-needed\fR, \fB\-\-no\-as\-needed\fR, and \fB\-a\fR. |
| 852 |
.Sp |
| 853 |
One target for this option are specifications for \fIpkg-config\fR. When |
| 854 |
used with the \fB\-\-libs\fR option all possibly needed libraries are |
| 855 |
listed and then possibly linked with all the time. It is better to return |
| 856 |
something as follows: |
| 857 |
.Sp |
| 858 |
.Vb 1 |
| 859 |
\& \-Wl,\-\-push\-state,\-\-as\-needed \-libone \-libtwo \-Wl,\-\-pop\-state |
| 860 |
.Ve |
| 861 |
.IP \fB\-\-pop\-state\fR 4 |
| 862 |
.IX Item "--pop-state" |
| 863 |
Undoes the effect of \fB\-\-push\-state\fR, restores the previous values |
| 864 |
of the flags governing input file handling. |
| 865 |
.IP \fB\-q\fR 4 |
| 866 |
.IX Item "-q" |
| 867 |
.PD 0 |
| 868 |
.IP \fB\-\-emit\-relocs\fR 4 |
| 869 |
.IX Item "--emit-relocs" |
| 870 |
.PD |
| 871 |
Leave relocation sections and contents in fully linked executables. |
| 872 |
Post link analysis and optimization tools may need this information in |
| 873 |
order to perform correct modifications of executables. This results |
| 874 |
in larger executables. |
| 875 |
.Sp |
| 876 |
This option is currently only supported on ELF platforms. |
| 877 |
.IP \fB\-\-force\-dynamic\fR 4 |
| 878 |
.IX Item "--force-dynamic" |
| 879 |
Force the output file to have dynamic sections. This option is specific |
| 880 |
to VxWorks targets. |
| 881 |
.IP \fB\-r\fR 4 |
| 882 |
.IX Item "-r" |
| 883 |
.PD 0 |
| 884 |
.IP \fB\-\-relocatable\fR 4 |
| 885 |
.IX Item "--relocatable" |
| 886 |
.PD |
| 887 |
Generate relocatable output\-\-\-i.e., generate an output file that can in |
| 888 |
turn serve as input to \fBld\fR. This is often called \fIpartial |
| 889 |
linking\fR. As a side effect, in environments that support standard Unix |
| 890 |
magic numbers, this option also sets the output file's magic number to |
| 891 |
\&\f(CW\*(C`OMAGIC\*(C'\fR. |
| 892 |
If this option is not specified, an absolute file is produced. When |
| 893 |
linking C++ programs, this option \fIwill not\fR resolve references to |
| 894 |
constructors; to do that, use \fB\-Ur\fR. |
| 895 |
.Sp |
| 896 |
When an input file does not have the same format as the output file, |
| 897 |
partial linking is only supported if that input file does not contain any |
| 898 |
relocations. Different output formats can have further restrictions; for |
| 899 |
example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking |
| 900 |
with input files in other formats at all. |
| 901 |
.Sp |
| 902 |
When the relocatable output contains both contents which require |
| 903 |
link-time optimization (LTO) and contents which don't require LTO, |
| 904 |
a .gnu_object_only section will be created to contain a relocatable |
| 905 |
object file, as if \fB\-r\fR is applied to all relocatable inputs |
| 906 |
which don't require LTO. When processing a relocatable input with |
| 907 |
a .gnu_object_only section, the linker will extract the .gnu_object_only |
| 908 |
section as a separate input. |
| 909 |
.Sp |
| 910 |
Note that since \fB\-r\fR groups some sections from different input files |
| 911 |
together, there may be negative impacts on code size and locality in |
| 912 |
final executable or shared library. |
| 913 |
.Sp |
| 914 |
This option does the same thing as \fB\-i\fR. |
| 915 |
.IP "\fB\-R\fR \fIfilename\fR" 4 |
| 916 |
.IX Item "-R filename" |
| 917 |
.PD 0 |
| 918 |
.IP \fB\-\-just\-symbols=\fR\fIfilename\fR 4 |
| 919 |
.IX Item "--just-symbols=filename" |
| 920 |
.PD |
| 921 |
Read symbol names and their addresses from \fIfilename\fR, but do not |
| 922 |
relocate it or include it in the output. This allows your output file |
| 923 |
to refer symbolically to absolute locations of memory defined in other |
| 924 |
programs. You may use this option more than once. |
| 925 |
.Sp |
| 926 |
For compatibility with other ELF linkers, if the \fB\-R\fR option is |
| 927 |
followed by a directory name, rather than a file name, it is treated as |
| 928 |
the \fB\-rpath\fR option. |
| 929 |
.IP \fB\-\-rosegment\fR 4 |
| 930 |
.IX Item "--rosegment" |
| 931 |
.PD 0 |
| 932 |
.IP \fB\-\-no\-rosegment\fR 4 |
| 933 |
.IX Item "--no-rosegment" |
| 934 |
.PD |
| 935 |
Attempt to ensure that only a single read-only, non-code segment is |
| 936 |
created. Only useful when used in conjunction with the \fB\-z |
| 937 |
separate-code\fR option. The resulting binaries should be smaller than |
| 938 |
if \fB\-z separate-code\fR is used on its own. Without this option, |
| 939 |
or if \fB\-\-no\-rosegment\fR is specified, the \fB\-z separate-code\fR |
| 940 |
option will create two read-only segments, one before the code segment |
| 941 |
and one after it. |
| 942 |
.Sp |
| 943 |
The name of the options are misleading, but they have been chosen in |
| 944 |
order for the linker to be compatible with the LLD and GOLD linkers. |
| 945 |
.Sp |
| 946 |
Thse options are only supported by ELF targets. |
| 947 |
.IP \fB\-s\fR 4 |
| 948 |
.IX Item "-s" |
| 949 |
.PD 0 |
| 950 |
.IP \fB\-\-strip\-all\fR 4 |
| 951 |
.IX Item "--strip-all" |
| 952 |
.PD |
| 953 |
Omit all symbol information from the output file. |
| 954 |
.IP \fB\-S\fR 4 |
| 955 |
.IX Item "-S" |
| 956 |
.PD 0 |
| 957 |
.IP \fB\-\-strip\-debug\fR 4 |
| 958 |
.IX Item "--strip-debug" |
| 959 |
.PD |
| 960 |
Omit debugger symbol information (but not all symbols) from the output file. |
| 961 |
.IP \fB\-\-strip\-discarded\fR 4 |
| 962 |
.IX Item "--strip-discarded" |
| 963 |
.PD 0 |
| 964 |
.IP \fB\-\-no\-strip\-discarded\fR 4 |
| 965 |
.IX Item "--no-strip-discarded" |
| 966 |
.PD |
| 967 |
Omit (or do not omit) global symbols defined in discarded sections. |
| 968 |
Enabled by default. |
| 969 |
.IP \fB\-plugin\-save\-temps\fR 4 |
| 970 |
.IX Item "-plugin-save-temps" |
| 971 |
Store the plugin "temporary" intermediate files permanently. |
| 972 |
.IP \fB\-t\fR 4 |
| 973 |
.IX Item "-t" |
| 974 |
.PD 0 |
| 975 |
.IP \fB\-\-trace\fR 4 |
| 976 |
.IX Item "--trace" |
| 977 |
.PD |
| 978 |
Print the names of the input files as \fBld\fR processes them. If |
| 979 |
\&\fB\-t\fR is given twice then members within archives are also printed. |
| 980 |
\&\fB\-t\fR output is useful to generate a list of all the object files |
| 981 |
and scripts involved in linking, for example, when packaging files for |
| 982 |
a linker bug report. |
| 983 |
.IP "\fB\-T\fR \fIscriptfile\fR" 4 |
| 984 |
.IX Item "-T scriptfile" |
| 985 |
.PD 0 |
| 986 |
.IP \fB\-\-script=\fR\fIscriptfile\fR 4 |
| 987 |
.IX Item "--script=scriptfile" |
| 988 |
.PD |
| 989 |
Use \fIscriptfile\fR as the linker script. This script replaces |
| 990 |
\&\fBld\fR's default linker script (rather than adding to it), |
| 991 |
unless the script contains \f(CW\*(C`INSERT\*(C'\fR, so \fIcommandfile\fR must |
| 992 |
specify everything necessary to describe the output file. |
| 993 |
.Sp |
| 994 |
If \fIscriptfile\fR does not exist in the current directory, \f(CW\*(C`ld\*(C'\fR |
| 995 |
looks for it in the directories specified by any preceding \fB\-L\fR |
| 996 |
options. |
| 997 |
.Sp |
| 998 |
Command line options that appear before the \fB\-T\fR option can |
| 999 |
affect the script, but command line options that appear after it do |
| 1000 |
not. |
| 1001 |
.Sp |
| 1002 |
Multiple \fB\-T\fR options will accumulate if they are augmenting the |
| 1003 |
current script, otherwise the last, non-augmenting, \fB\-T\fR option |
| 1004 |
will be used. |
| 1005 |
.Sp |
| 1006 |
There are other ways of specifying linker scripts. See |
| 1007 |
.IP "\fB\-dT\fR \fIscriptfile\fR" 4 |
| 1008 |
.IX Item "-dT scriptfile" |
| 1009 |
.PD 0 |
| 1010 |
.IP \fB\-\-default\-script=\fR\fIscriptfile\fR 4 |
| 1011 |
.IX Item "--default-script=scriptfile" |
| 1012 |
.PD |
| 1013 |
Use \fIscriptfile\fR as the default linker script. |
| 1014 |
.Sp |
| 1015 |
This option is similar to the \fB\-\-script\fR option except that |
| 1016 |
processing of the script is delayed until after the rest of the |
| 1017 |
command line has been processed. This allows options placed after the |
| 1018 |
\&\fB\-\-default\-script\fR option on the command line to affect the |
| 1019 |
behaviour of the linker script, which can be important when the linker |
| 1020 |
command line cannot be directly controlled by the user. (eg because |
| 1021 |
the command line is being constructed by another tool, such as |
| 1022 |
\&\fBgcc\fR). |
| 1023 |
.IP "\fB\-u\fR \fIsymbol\fR" 4 |
| 1024 |
.IX Item "-u symbol" |
| 1025 |
.PD 0 |
| 1026 |
.IP \fB\-\-undefined=\fR\fIsymbol\fR 4 |
| 1027 |
.IX Item "--undefined=symbol" |
| 1028 |
.PD |
| 1029 |
Force \fIsymbol\fR to be entered in the output file as an undefined |
| 1030 |
symbol. Doing this may, for example, trigger linking of additional |
| 1031 |
modules from standard libraries. \fB\-u\fR may be repeated with |
| 1032 |
different option arguments to enter additional undefined symbols. This |
| 1033 |
option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command. |
| 1034 |
.Sp |
| 1035 |
If this option is being used to force additional modules to be pulled |
| 1036 |
into the link, and if it is an error for the symbol to remain |
| 1037 |
undefined, then the option \fB\-\-require\-defined\fR should be used |
| 1038 |
instead. |
| 1039 |
.IP \fB\-\-require\-defined=\fR\fIsymbol\fR 4 |
| 1040 |
.IX Item "--require-defined=symbol" |
| 1041 |
Require that \fIsymbol\fR is defined in the output file. This option |
| 1042 |
is the same as option \fB\-\-undefined\fR except that if \fIsymbol\fR |
| 1043 |
is not defined in the output file then the linker will issue an error |
| 1044 |
and exit. The same effect can be achieved in a linker script by using |
| 1045 |
\&\f(CW\*(C`EXTERN\*(C'\fR, \f(CW\*(C`ASSERT\*(C'\fR and \f(CW\*(C`DEFINED\*(C'\fR together. This option |
| 1046 |
can be used multiple times to require additional symbols. |
| 1047 |
.IP \fB\-Ur\fR 4 |
| 1048 |
.IX Item "-Ur" |
| 1049 |
For programs that do not use constructors or destructors, or for ELF |
| 1050 |
based systems this option is equivalent to \fB\-r\fR: it generates |
| 1051 |
relocatable output\-\-\-i.e., an output file that can in turn serve as |
| 1052 |
input to \fBld\fR. For other binaries however the \fB\-Ur\fR |
| 1053 |
option is similar to \fB\-r\fR but it also resolves references to |
| 1054 |
constructors and destructors. |
| 1055 |
.Sp |
| 1056 |
For those systems where \fB\-r\fR and \fB\-Ur\fR behave |
| 1057 |
differently, it does not work to use \fB\-Ur\fR on files that were |
| 1058 |
themselves linked with \fB\-Ur\fR; once the constructor table has |
| 1059 |
been built, it cannot be added to. Use \fB\-Ur\fR only for the last |
| 1060 |
partial link, and \fB\-r\fR for the others. |
| 1061 |
.IP \fB\-\-orphan\-handling=\fR\fIMODE\fR 4 |
| 1062 |
.IX Item "--orphan-handling=MODE" |
| 1063 |
Control how orphan sections are handled. An orphan section is one not |
| 1064 |
specifically mentioned in a linker script. |
| 1065 |
.Sp |
| 1066 |
\&\fIMODE\fR can have any of the following values: |
| 1067 |
.RS 4 |
| 1068 |
.ie n .IP """place""" 4 |
| 1069 |
.el .IP \f(CWplace\fR 4 |
| 1070 |
.IX Item "place" |
| 1071 |
Orphan sections are placed into a suitable output section following |
| 1072 |
the strategy described in \fBOrphan Sections\fR. The option |
| 1073 |
\&\fB\-\-unique\fR also affects how sections are placed. |
| 1074 |
.ie n .IP """discard""" 4 |
| 1075 |
.el .IP \f(CWdiscard\fR 4 |
| 1076 |
.IX Item "discard" |
| 1077 |
All orphan sections are discarded, by placing them in the |
| 1078 |
\&\fB/DISCARD/\fR section. |
| 1079 |
.ie n .IP """warn""" 4 |
| 1080 |
.el .IP \f(CWwarn\fR 4 |
| 1081 |
.IX Item "warn" |
| 1082 |
The linker will place the orphan section as for \f(CW\*(C`place\*(C'\fR and also |
| 1083 |
issue a warning. |
| 1084 |
.ie n .IP """error""" 4 |
| 1085 |
.el .IP \f(CWerror\fR 4 |
| 1086 |
.IX Item "error" |
| 1087 |
The linker will exit with an error if any orphan section is found. |
| 1088 |
.RE |
| 1089 |
.RS 4 |
| 1090 |
.Sp |
| 1091 |
The default if \fB\-\-orphan\-handling\fR is not given is \f(CW\*(C`place\*(C'\fR. |
| 1092 |
.RE |
| 1093 |
.IP \fB\-\-unique[=\fR\fISECTION\fR\fB]\fR 4 |
| 1094 |
.IX Item "--unique[=SECTION]" |
| 1095 |
Creates a separate output section for every input section matching |
| 1096 |
\&\fISECTION\fR, or if the optional wildcard \fISECTION\fR argument is |
| 1097 |
missing, for every orphan input section. An orphan section is one not |
| 1098 |
specifically mentioned in a linker script. You may use this option |
| 1099 |
multiple times on the command line; It prevents the normal merging of |
| 1100 |
input sections with the same name, overriding output section assignments |
| 1101 |
in a linker script. |
| 1102 |
.IP \fB\-v\fR 4 |
| 1103 |
.IX Item "-v" |
| 1104 |
.PD 0 |
| 1105 |
.IP \fB\-\-version\fR 4 |
| 1106 |
.IX Item "--version" |
| 1107 |
.IP \fB\-V\fR 4 |
| 1108 |
.IX Item "-V" |
| 1109 |
.PD |
| 1110 |
Display the version number for \fBld\fR. The \fB\-V\fR option also |
| 1111 |
lists the supported emulations. See also the description of the |
| 1112 |
\&\fB\-\-enable\-linker\-version\fR in \fBOptions,,Command\-line Options\fR |
| 1113 |
which can be used to insert the linker version string into a binary. |
| 1114 |
.IP \fB\-x\fR 4 |
| 1115 |
.IX Item "-x" |
| 1116 |
.PD 0 |
| 1117 |
.IP \fB\-\-discard\-all\fR 4 |
| 1118 |
.IX Item "--discard-all" |
| 1119 |
.PD |
| 1120 |
Delete all local symbols. |
| 1121 |
.IP \fB\-X\fR 4 |
| 1122 |
.IX Item "-X" |
| 1123 |
.PD 0 |
| 1124 |
.IP \fB\-\-discard\-locals\fR 4 |
| 1125 |
.IX Item "--discard-locals" |
| 1126 |
.PD |
| 1127 |
Delete all temporary local symbols. (These symbols start with |
| 1128 |
system-specific local label prefixes, typically \fB.L\fR for ELF systems |
| 1129 |
or \fBL\fR for traditional a.out systems.) |
| 1130 |
.IP "\fB\-y\fR \fIsymbol\fR" 4 |
| 1131 |
.IX Item "-y symbol" |
| 1132 |
.PD 0 |
| 1133 |
.IP \fB\-\-trace\-symbol=\fR\fIsymbol\fR 4 |
| 1134 |
.IX Item "--trace-symbol=symbol" |
| 1135 |
.PD |
| 1136 |
Print the name of each linked file in which \fIsymbol\fR appears. This |
| 1137 |
option may be given any number of times. On many systems it is necessary |
| 1138 |
to prepend an underscore. |
| 1139 |
.Sp |
| 1140 |
This option is useful when you have an undefined symbol in your link but |
| 1141 |
don't know where the reference is coming from. |
| 1142 |
.IP "\fB\-Y\fR \fIpath\fR" 4 |
| 1143 |
.IX Item "-Y path" |
| 1144 |
Add \fIpath\fR to the default library search path. This option exists |
| 1145 |
for Solaris compatibility. |
| 1146 |
.IP "\fB\-z\fR \fIkeyword\fR" 4 |
| 1147 |
.IX Item "-z keyword" |
| 1148 |
The recognized keywords are: |
| 1149 |
.RS 4 |
| 1150 |
.IP \fBcall\-nop=prefix\-addr\fR 4 |
| 1151 |
.IX Item "call-nop=prefix-addr" |
| 1152 |
.PD 0 |
| 1153 |
.IP \fBcall\-nop=suffix\-nop\fR 4 |
| 1154 |
.IX Item "call-nop=suffix-nop" |
| 1155 |
.IP \fBcall\-nop=prefix\-\fR\fIbyte\fR 4 |
| 1156 |
.IX Item "call-nop=prefix-byte" |
| 1157 |
.IP \fBcall\-nop=suffix\-\fR\fIbyte\fR 4 |
| 1158 |
.IX Item "call-nop=suffix-byte" |
| 1159 |
.PD |
| 1160 |
Specify the 1\-byte \f(CW\*(C`NOP\*(C'\fR padding when transforming indirect call |
| 1161 |
to a locally defined function, foo, via its GOT slot. |
| 1162 |
\&\fBcall\-nop=prefix\-addr\fR generates \f(CW\*(C`0x67 call foo\*(C'\fR. |
| 1163 |
\&\fBcall\-nop=suffix\-nop\fR generates \f(CW\*(C`call foo 0x90\*(C'\fR. |
| 1164 |
\&\fBcall\-nop=prefix\-\fR\fIbyte\fR generates \f(CW\*(C`\fR\f(CIbyte\fR\f(CW call foo\*(C'\fR. |
| 1165 |
\&\fBcall\-nop=suffix\-\fR\fIbyte\fR generates \f(CW\*(C`call foo \fR\f(CIbyte\fR\f(CW\*(C'\fR. |
| 1166 |
Supported for i386 and x86_64. |
| 1167 |
.IP \fBcet\-report=none\fR 4 |
| 1168 |
.IX Item "cet-report=none" |
| 1169 |
.PD 0 |
| 1170 |
.IP \fBcet\-report=warning\fR 4 |
| 1171 |
.IX Item "cet-report=warning" |
| 1172 |
.IP \fBcet\-report=error\fR 4 |
| 1173 |
.IX Item "cet-report=error" |
| 1174 |
.PD |
| 1175 |
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT and |
| 1176 |
GNU_PROPERTY_X86_FEATURE_1_SHSTK properties in input .note.gnu.property |
| 1177 |
section. \fBcet\-report=none\fR, which is the default, will make the |
| 1178 |
linker not report missing properties in input files. |
| 1179 |
\&\fBcet\-report=warning\fR will make the linker issue a warning for |
| 1180 |
missing properties in input files. \fBcet\-report=error\fR will make |
| 1181 |
the linker issue an error for missing properties in input files. |
| 1182 |
Note that \fBibt\fR will turn off the missing |
| 1183 |
GNU_PROPERTY_X86_FEATURE_1_IBT property report and \fBshstk\fR will |
| 1184 |
turn off the missing GNU_PROPERTY_X86_FEATURE_1_SHSTK property report. |
| 1185 |
Supported for Linux/i386 and Linux/x86_64. |
| 1186 |
.IP \fBcombreloc\fR 4 |
| 1187 |
.IX Item "combreloc" |
| 1188 |
.PD 0 |
| 1189 |
.IP \fBnocombreloc\fR 4 |
| 1190 |
.IX Item "nocombreloc" |
| 1191 |
.PD |
| 1192 |
Combine multiple dynamic relocation sections and sort to improve |
| 1193 |
dynamic symbol lookup caching. Do not do this if \fBnocombreloc\fR. |
| 1194 |
.IP \fBcommon\fR 4 |
| 1195 |
.IX Item "common" |
| 1196 |
.PD 0 |
| 1197 |
.IP \fBnocommon\fR 4 |
| 1198 |
.IX Item "nocommon" |
| 1199 |
.PD |
| 1200 |
Generate common symbols with STT_COMMON type during a relocatable |
| 1201 |
link. Use STT_OBJECT type if \fBnocommon\fR. |
| 1202 |
.IP \fBcommon\-page\-size=\fR\fIvalue\fR 4 |
| 1203 |
.IX Item "common-page-size=value" |
| 1204 |
Set the page size most commonly used to \fIvalue\fR. Memory image |
| 1205 |
layout will be optimized to minimize memory pages if the system is |
| 1206 |
using pages of this size. |
| 1207 |
.IP \fBdefs\fR 4 |
| 1208 |
.IX Item "defs" |
| 1209 |
Report unresolved symbol references from regular object files. This |
| 1210 |
is done even if the linker is creating a non-symbolic shared library. |
| 1211 |
This option is the inverse of \fB\-z undefs\fR. |
| 1212 |
.IP \fBdynamic-undefined-weak\fR 4 |
| 1213 |
.IX Item "dynamic-undefined-weak" |
| 1214 |
.PD 0 |
| 1215 |
.IP \fBnodynamic-undefined-weak\fR 4 |
| 1216 |
.IX Item "nodynamic-undefined-weak" |
| 1217 |
.PD |
| 1218 |
Make undefined weak symbols dynamic when building a dynamic object, |
| 1219 |
if they are referenced from a regular object file and not forced local |
| 1220 |
by symbol visibility or versioning. Do not make them dynamic if |
| 1221 |
\&\fBnodynamic-undefined-weak\fR. If neither option is given, a target |
| 1222 |
may default to either option being in force, or make some other |
| 1223 |
selection of undefined weak symbols dynamic. Not all targets support |
| 1224 |
these options. |
| 1225 |
.IP \fBexecstack\fR 4 |
| 1226 |
.IX Item "execstack" |
| 1227 |
Marks the object as requiring executable stack. |
| 1228 |
.IP \fBglobal\fR 4 |
| 1229 |
.IX Item "global" |
| 1230 |
This option is only meaningful when building a shared object. It makes |
| 1231 |
the symbols defined by this shared object available for symbol resolution |
| 1232 |
of subsequently loaded libraries. |
| 1233 |
.IP \fBglobalaudit\fR 4 |
| 1234 |
.IX Item "globalaudit" |
| 1235 |
This option is only meaningful when building a dynamic executable. |
| 1236 |
This option marks the executable as requiring global auditing by |
| 1237 |
setting the \f(CW\*(C`DF_1_GLOBAUDIT\*(C'\fR bit in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR dynamic |
| 1238 |
tag. Global auditing requires that any auditing library defined via |
| 1239 |
the \fB\-\-depaudit\fR or \fB\-P\fR command-line options be run for |
| 1240 |
all dynamic objects loaded by the application. |
| 1241 |
.IP \fBibtplt\fR 4 |
| 1242 |
.IX Item "ibtplt" |
| 1243 |
Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries. |
| 1244 |
Supported for Linux/i386 and Linux/x86_64. |
| 1245 |
.IP \fBibt\fR 4 |
| 1246 |
.IX Item "ibt" |
| 1247 |
Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section |
| 1248 |
to indicate compatibility with IBT. This also implies \fBibtplt\fR. |
| 1249 |
Supported for Linux/i386 and Linux/x86_64. |
| 1250 |
.IP \fBindirect-extern-access\fR 4 |
| 1251 |
.IX Item "indirect-extern-access" |
| 1252 |
.PD 0 |
| 1253 |
.IP \fBnoindirect-extern-access\fR 4 |
| 1254 |
.IX Item "noindirect-extern-access" |
| 1255 |
.PD |
| 1256 |
Generate GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS in |
| 1257 |
\&.note.gnu.property section to indicate that object file requires |
| 1258 |
canonical function pointers and cannot be used with copy relocation. |
| 1259 |
This option also implies \fBnoextern-protected-data\fR and |
| 1260 |
\&\fBnocopyreloc\fR. Supported for i386 and x86\-64. |
| 1261 |
.Sp |
| 1262 |
\&\fBnoindirect-extern-access\fR removes |
| 1263 |
GNU_PROPERTY_1_NEEDED_INDIRECT_EXTERN_ACCESS from .note.gnu.property |
| 1264 |
section. |
| 1265 |
.IP \fBinitfirst\fR 4 |
| 1266 |
.IX Item "initfirst" |
| 1267 |
This option is only meaningful when building a shared object. |
| 1268 |
It marks the object so that its runtime initialization will occur |
| 1269 |
before the runtime initialization of any other objects brought into |
| 1270 |
the process at the same time. Similarly the runtime finalization of |
| 1271 |
the object will occur after the runtime finalization of any other |
| 1272 |
objects. |
| 1273 |
.IP \fBinterpose\fR 4 |
| 1274 |
.IX Item "interpose" |
| 1275 |
Specify that the dynamic loader should modify its symbol search order |
| 1276 |
so that symbols in this shared library interpose all other shared |
| 1277 |
libraries not so marked. |
| 1278 |
.IP \fBunique\fR 4 |
| 1279 |
.IX Item "unique" |
| 1280 |
.PD 0 |
| 1281 |
.IP \fBnounique\fR 4 |
| 1282 |
.IX Item "nounique" |
| 1283 |
.PD |
| 1284 |
When generating a shared library or other dynamically loadable ELF |
| 1285 |
object mark it as one that should (by default) only ever be loaded once, |
| 1286 |
and only in the main namespace (when using \f(CW\*(C`dlmopen\*(C'\fR). This is |
| 1287 |
primarily used to mark fundamental libraries such as libc, libpthread et |
| 1288 |
al which do not usually function correctly unless they are the sole instances |
| 1289 |
of themselves. This behaviour can be overridden by the \f(CW\*(C`dlmopen\*(C'\fR caller |
| 1290 |
and does not apply to certain loading mechanisms (such as audit libraries). |
| 1291 |
.IP \fBlam\-u48\fR 4 |
| 1292 |
.IX Item "lam-u48" |
| 1293 |
Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U48 in .note.gnu.property section |
| 1294 |
to indicate compatibility with Intel LAM_U48. Supported for Linux/x86_64. |
| 1295 |
.IP \fBlam\-u57\fR 4 |
| 1296 |
.IX Item "lam-u57" |
| 1297 |
Generate GNU_PROPERTY_X86_FEATURE_1_LAM_U57 in .note.gnu.property section |
| 1298 |
to indicate compatibility with Intel LAM_U57. Supported for Linux/x86_64. |
| 1299 |
.IP \fBlam\-u48\-report=none\fR 4 |
| 1300 |
.IX Item "lam-u48-report=none" |
| 1301 |
.PD 0 |
| 1302 |
.IP \fBlam\-u48\-report=warning\fR 4 |
| 1303 |
.IX Item "lam-u48-report=warning" |
| 1304 |
.IP \fBlam\-u48\-report=error\fR 4 |
| 1305 |
.IX Item "lam-u48-report=error" |
| 1306 |
.PD |
| 1307 |
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 |
| 1308 |
property in input .note.gnu.property section. |
| 1309 |
\&\fBlam\-u48\-report=none\fR, which is the default, will make the |
| 1310 |
linker not report missing properties in input files. |
| 1311 |
\&\fBlam\-u48\-report=warning\fR will make the linker issue a warning for |
| 1312 |
missing properties in input files. \fBlam\-u48\-report=error\fR will |
| 1313 |
make the linker issue an error for missing properties in input files. |
| 1314 |
Supported for Linux/x86_64. |
| 1315 |
.IP \fBlam\-u57\-report=none\fR 4 |
| 1316 |
.IX Item "lam-u57-report=none" |
| 1317 |
.PD 0 |
| 1318 |
.IP \fBlam\-u57\-report=warning\fR 4 |
| 1319 |
.IX Item "lam-u57-report=warning" |
| 1320 |
.IP \fBlam\-u57\-report=error\fR 4 |
| 1321 |
.IX Item "lam-u57-report=error" |
| 1322 |
.PD |
| 1323 |
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U57 |
| 1324 |
property in input .note.gnu.property section. |
| 1325 |
\&\fBlam\-u57\-report=none\fR, which is the default, will make the |
| 1326 |
linker not report missing properties in input files. |
| 1327 |
\&\fBlam\-u57\-report=warning\fR will make the linker issue a warning for |
| 1328 |
missing properties in input files. \fBlam\-u57\-report=error\fR will |
| 1329 |
make the linker issue an error for missing properties in input files. |
| 1330 |
Supported for Linux/x86_64. |
| 1331 |
.IP \fBlam\-report=none\fR 4 |
| 1332 |
.IX Item "lam-report=none" |
| 1333 |
.PD 0 |
| 1334 |
.IP \fBlam\-report=warning\fR 4 |
| 1335 |
.IX Item "lam-report=warning" |
| 1336 |
.IP \fBlam\-report=error\fR 4 |
| 1337 |
.IX Item "lam-report=error" |
| 1338 |
.PD |
| 1339 |
Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_LAM_U48 and |
| 1340 |
GNU_PROPERTY_X86_FEATURE_1_LAM_U57 properties in input .note.gnu.property |
| 1341 |
section. \fBlam\-report=none\fR, which is the default, will make the |
| 1342 |
linker not report missing properties in input files. |
| 1343 |
\&\fBlam\-report=warning\fR will make the linker issue a warning for |
| 1344 |
missing properties in input files. \fBlam\-report=error\fR will make |
| 1345 |
the linker issue an error for missing properties in input files. |
| 1346 |
Supported for Linux/x86_64. |
| 1347 |
.IP \fBlazy\fR 4 |
| 1348 |
.IX Item "lazy" |
| 1349 |
When generating an executable or shared library, mark it to tell the |
| 1350 |
dynamic linker to defer function call resolution to the point when |
| 1351 |
the function is called (lazy binding), rather than at load time. |
| 1352 |
Lazy binding is the default. |
| 1353 |
.IP \fBloadfltr\fR 4 |
| 1354 |
.IX Item "loadfltr" |
| 1355 |
Specify that the object's filters be processed immediately at runtime. |
| 1356 |
.IP \fBmax\-page\-size=\fR\fIvalue\fR 4 |
| 1357 |
.IX Item "max-page-size=value" |
| 1358 |
Set the maximum memory page size supported to \fIvalue\fR. |
| 1359 |
.IP \fBmark-plt\fR 4 |
| 1360 |
.IX Item "mark-plt" |
| 1361 |
.PD 0 |
| 1362 |
.IP \fBnomark-plt\fR 4 |
| 1363 |
.IX Item "nomark-plt" |
| 1364 |
.PD |
| 1365 |
Mark PLT entries with dynamic tags, DT_X86_64_PLT, DT_X86_64_PLTSZ and |
| 1366 |
DT_X86_64_PLTENT. Since this option stores a non-zero value in the |
| 1367 |
r_addend field of R_X86_64_JUMP_SLOT relocations, the resulting |
| 1368 |
executables and shared libraries are incompatible with dynamic linkers, |
| 1369 |
such as those in older versions of glibc without the change to ignore |
| 1370 |
r_addend in R_X86_64_GLOB_DAT and R_X86_64_JUMP_SLOT relocations, which |
| 1371 |
don't ignore the r_addend field of R_X86_64_JUMP_SLOT relocations. |
| 1372 |
Supported for x86_64. |
| 1373 |
.IP \fBmuldefs\fR 4 |
| 1374 |
.IX Item "muldefs" |
| 1375 |
Allow multiple definitions. |
| 1376 |
.IP \fBnocopyreloc\fR 4 |
| 1377 |
.IX Item "nocopyreloc" |
| 1378 |
Disable linker generated .dynbss variables used in place of variables |
| 1379 |
defined in shared libraries. May result in dynamic text relocations. |
| 1380 |
.IP \fBnodefaultlib\fR 4 |
| 1381 |
.IX Item "nodefaultlib" |
| 1382 |
Specify that the dynamic loader search for dependencies of this object |
| 1383 |
should ignore any default library search paths. |
| 1384 |
.IP \fBnodelete\fR 4 |
| 1385 |
.IX Item "nodelete" |
| 1386 |
Specify that the object shouldn't be unloaded at runtime. |
| 1387 |
.IP \fBnodlopen\fR 4 |
| 1388 |
.IX Item "nodlopen" |
| 1389 |
Specify that the object is not available to \f(CW\*(C`dlopen\*(C'\fR. |
| 1390 |
.IP \fBnodump\fR 4 |
| 1391 |
.IX Item "nodump" |
| 1392 |
Specify that the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. |
| 1393 |
.IP \fBnoexecstack\fR 4 |
| 1394 |
.IX Item "noexecstack" |
| 1395 |
Marks the object as not requiring executable stack. |
| 1396 |
.IP \fBnoextern-protected-data\fR 4 |
| 1397 |
.IX Item "noextern-protected-data" |
| 1398 |
Don't treat protected data symbols as external when building a shared |
| 1399 |
library. This option overrides the linker backend default. It can be |
| 1400 |
used to work around incorrect relocations against protected data symbols |
| 1401 |
generated by compiler. Updates on protected data symbols by another |
| 1402 |
module aren't visible to the resulting shared library. Supported for |
| 1403 |
i386 and x86\-64. |
| 1404 |
.IP \fBnoreloc-overflow\fR 4 |
| 1405 |
.IX Item "noreloc-overflow" |
| 1406 |
Disable relocation overflow check. This can be used to disable |
| 1407 |
relocation overflow check if there will be no dynamic relocation |
| 1408 |
overflow at run-time. Supported for x86_64. |
| 1409 |
.IP \fBmemory-seal\fR 4 |
| 1410 |
.IX Item "memory-seal" |
| 1411 |
.PD 0 |
| 1412 |
.IP \fBnomemory-seal\fR 4 |
| 1413 |
.IX Item "nomemory-seal" |
| 1414 |
.PD |
| 1415 |
Instruct the executable or shared library that the all PT_LOAD segments |
| 1416 |
should be sealed to avoid further manipulation (such as changing the |
| 1417 |
protection flags, the segment size, or remove the mapping). |
| 1418 |
This is a security hardening that requires system support. This |
| 1419 |
generates GNU_PROPERTY_MEMORY_SEAL in .note.gnu.property section |
| 1420 |
.IP \fBnow\fR 4 |
| 1421 |
.IX Item "now" |
| 1422 |
When generating an executable or shared library, mark it to tell the |
| 1423 |
dynamic linker to resolve all symbols when the program is started, or |
| 1424 |
when the shared library is loaded by dlopen, instead of deferring |
| 1425 |
function call resolution to the point when the function is first |
| 1426 |
called. |
| 1427 |
.IP \fBorigin\fR 4 |
| 1428 |
.IX Item "origin" |
| 1429 |
Specify that the object requires \fR\f(CB$ORIGIN\fR\fB\fR handling in paths. |
| 1430 |
.IP \fBpack-relative-relocs\fR 4 |
| 1431 |
.IX Item "pack-relative-relocs" |
| 1432 |
.PD 0 |
| 1433 |
.IP \fBnopack-relative-relocs\fR 4 |
| 1434 |
.IX Item "nopack-relative-relocs" |
| 1435 |
.PD |
| 1436 |
Generate compact relative relocation in position-independent executable |
| 1437 |
and shared library. It adds \f(CW\*(C`DT_RELR\*(C'\fR, \f(CW\*(C`DT_RELRSZ\*(C'\fR and |
| 1438 |
\&\f(CW\*(C`DT_RELRENT\*(C'\fR entries to the dynamic section. It is ignored when |
| 1439 |
building position-dependent executable and relocatable output. |
| 1440 |
\&\fBnopack-relative-relocs\fR is the default, which disables compact |
| 1441 |
relative relocation. When linked against the GNU C Library, a |
| 1442 |
GLIBC_ABI_DT_RELR symbol version dependency on the shared C Library is |
| 1443 |
added to the output. Supported for i386 and x86\-64. |
| 1444 |
.IP \fBrelro\fR 4 |
| 1445 |
.IX Item "relro" |
| 1446 |
.PD 0 |
| 1447 |
.IP \fBnorelro\fR 4 |
| 1448 |
.IX Item "norelro" |
| 1449 |
.PD |
| 1450 |
Create an ELF \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object. This |
| 1451 |
specifies a memory segment that should be made read-only after |
| 1452 |
relocation, if supported. Specifying \fBcommon-page-size\fR smaller |
| 1453 |
than the system page size will render this protection ineffective. |
| 1454 |
Don't create an ELF \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment if \fBnorelro\fR. |
| 1455 |
.IP \fBreport-relative-reloc\fR 4 |
| 1456 |
.IX Item "report-relative-reloc" |
| 1457 |
Report dynamic relative relocations generated by linker. Supported for |
| 1458 |
Linux/i386 and Linux/x86_64. |
| 1459 |
.IP \fBsectionheader\fR 4 |
| 1460 |
.IX Item "sectionheader" |
| 1461 |
.PD 0 |
| 1462 |
.IP \fBnosectionheader\fR 4 |
| 1463 |
.IX Item "nosectionheader" |
| 1464 |
.PD |
| 1465 |
Generate section header. Don't generate section header if |
| 1466 |
\&\fBnosectionheader\fR is used. \fBsectionheader\fR is the default. |
| 1467 |
.IP \fBseparate-code\fR 4 |
| 1468 |
.IX Item "separate-code" |
| 1469 |
.PD 0 |
| 1470 |
.IP \fBnoseparate-code\fR 4 |
| 1471 |
.IX Item "noseparate-code" |
| 1472 |
.PD |
| 1473 |
Create separate code \f(CW\*(C`PT_LOAD\*(C'\fR segment header in the object. This |
| 1474 |
specifies a memory segment that should contain only instructions and must |
| 1475 |
be in wholly disjoint pages from any other data. Don't create separate |
| 1476 |
code \f(CW\*(C`PT_LOAD\*(C'\fR segment if \fBnoseparate-code\fR is used. |
| 1477 |
.IP \fBshstk\fR 4 |
| 1478 |
.IX Item "shstk" |
| 1479 |
Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section |
| 1480 |
to indicate compatibility with Intel Shadow Stack. Supported for |
| 1481 |
Linux/i386 and Linux/x86_64. |
| 1482 |
.IP \fBstack\-size=\fR\fIvalue\fR 4 |
| 1483 |
.IX Item "stack-size=value" |
| 1484 |
Specify a stack size for an ELF \f(CW\*(C`PT_GNU_STACK\*(C'\fR segment. |
| 1485 |
Specifying zero will override any default non-zero sized |
| 1486 |
\&\f(CW\*(C`PT_GNU_STACK\*(C'\fR segment creation. |
| 1487 |
.IP \fBstart-stop-gc\fR 4 |
| 1488 |
.IX Item "start-stop-gc" |
| 1489 |
.PD 0 |
| 1490 |
.IP \fBnostart-stop-gc\fR 4 |
| 1491 |
.IX Item "nostart-stop-gc" |
| 1492 |
.PD |
| 1493 |
When \fB\-\-gc\-sections\fR is in effect, a reference from a retained |
| 1494 |
section to \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR causes all |
| 1495 |
input sections named \f(CW\*(C`SECNAME\*(C'\fR to also be retained, if |
| 1496 |
\&\f(CW\*(C`SECNAME\*(C'\fR is representable as a C identifier and either |
| 1497 |
\&\f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR is synthesized by the |
| 1498 |
linker. \fB\-z start-stop-gc\fR disables this effect, allowing |
| 1499 |
sections to be garbage collected as if the special synthesized symbols |
| 1500 |
were not defined. \fB\-z start-stop-gc\fR has no effect on a |
| 1501 |
definition of \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR in an |
| 1502 |
object file or linker script. Such a definition will prevent the |
| 1503 |
linker providing a synthesized \f(CW\*(C`_\|_start_SECNAME\*(C'\fR or |
| 1504 |
\&\f(CW\*(C`_\|_stop_SECNAME\*(C'\fR respectively, and therefore the special |
| 1505 |
treatment by garbage collection for those references. |
| 1506 |
.IP \fBstart\-stop\-visibility=\fR\fIvalue\fR 4 |
| 1507 |
.IX Item "start-stop-visibility=value" |
| 1508 |
Specify the ELF symbol visibility for synthesized |
| 1509 |
\&\f(CW\*(C`_\|_start_SECNAME\*(C'\fR and \f(CW\*(C`_\|_stop_SECNAME\*(C'\fR symbols. \fIvalue\fR must be exactly \fBdefault\fR, |
| 1510 |
\&\fBinternal\fR, \fBhidden\fR, or \fBprotected\fR. If no \fB\-z |
| 1511 |
start-stop-visibility\fR option is given, \fBprotected\fR is used for |
| 1512 |
compatibility with historical practice. However, it's highly |
| 1513 |
recommended to use \fB\-z start\-stop\-visibility=hidden\fR in new |
| 1514 |
programs and shared libraries so that these symbols are not exported |
| 1515 |
between shared objects, which is not usually what's intended. |
| 1516 |
.IP \fBtext\fR 4 |
| 1517 |
.IX Item "text" |
| 1518 |
.PD 0 |
| 1519 |
.IP \fBnotext\fR 4 |
| 1520 |
.IX Item "notext" |
| 1521 |
.IP \fBtextoff\fR 4 |
| 1522 |
.IX Item "textoff" |
| 1523 |
.PD |
| 1524 |
Report an error if DT_TEXTREL is set, i.e., if the position-independent |
| 1525 |
or shared object has dynamic relocations in read-only sections. Don't |
| 1526 |
report an error if \fBnotext\fR or \fBtextoff\fR. |
| 1527 |
.IP \fBundefs\fR 4 |
| 1528 |
.IX Item "undefs" |
| 1529 |
Do not report unresolved symbol references from regular object files, |
| 1530 |
either when creating an executable, or when creating a shared library. |
| 1531 |
This option is the inverse of \fB\-z defs\fR. |
| 1532 |
.IP \fBunique-symbol\fR 4 |
| 1533 |
.IX Item "unique-symbol" |
| 1534 |
.PD 0 |
| 1535 |
.IP \fBnounique-symbol\fR 4 |
| 1536 |
.IX Item "nounique-symbol" |
| 1537 |
.PD |
| 1538 |
Avoid duplicated local symbol names in the symbol string table. Append |
| 1539 |
".\f(CW\*(C`number\*(C'\fR" to duplicated local symbol names if \fBunique-symbol\fR |
| 1540 |
is used. \fBnounique-symbol\fR is the default. |
| 1541 |
.IP \fBx86\-64\-baseline\fR 4 |
| 1542 |
.IX Item "x86-64-baseline" |
| 1543 |
.PD 0 |
| 1544 |
.IP \fBx86\-64\-v2\fR 4 |
| 1545 |
.IX Item "x86-64-v2" |
| 1546 |
.IP \fBx86\-64\-v3\fR 4 |
| 1547 |
.IX Item "x86-64-v3" |
| 1548 |
.IP \fBx86\-64\-v4\fR 4 |
| 1549 |
.IX Item "x86-64-v4" |
| 1550 |
.PD |
| 1551 |
Specify the x86\-64 ISA level needed in .note.gnu.property section. |
| 1552 |
\&\fBx86\-64\-baseline\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_BASELINE\*(C'\fR. |
| 1553 |
\&\fBx86\-64\-v2\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V2\*(C'\fR. |
| 1554 |
\&\fBx86\-64\-v3\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V3\*(C'\fR. |
| 1555 |
\&\fBx86\-64\-v4\fR generates \f(CW\*(C`GNU_PROPERTY_X86_ISA_1_V4\*(C'\fR. |
| 1556 |
Supported for Linux/i386 and Linux/x86_64. |
| 1557 |
.IP \fBisa\-level\-report=none\fR 4 |
| 1558 |
.IX Item "isa-level-report=none" |
| 1559 |
.PD 0 |
| 1560 |
.IP \fBisa\-level\-report=all\fR 4 |
| 1561 |
.IX Item "isa-level-report=all" |
| 1562 |
.IP \fBisa\-level\-report=needed\fR 4 |
| 1563 |
.IX Item "isa-level-report=needed" |
| 1564 |
.IP \fBisa\-level\-report=used\fR 4 |
| 1565 |
.IX Item "isa-level-report=used" |
| 1566 |
.PD |
| 1567 |
Specify how to report x86\-64 ISA levels in input relocatable files. |
| 1568 |
\&\fBisa\-level\-report=none\fR, which is the default, will make the |
| 1569 |
linker not report x86\-64 ISA levels in input files. |
| 1570 |
\&\fBisa\-level\-report=all\fR will make the linker report needed and |
| 1571 |
used x86\-64 ISA levels in input files. |
| 1572 |
\&\fBisa\-level\-report=needed\fR will make the linker report needed |
| 1573 |
x86\-64 ISA levels in input files. |
| 1574 |
\&\fBisa\-level\-report=used\fR will make the linker report used |
| 1575 |
x86\-64 ISA levels in input files. |
| 1576 |
Supported for Linux/i386 and Linux/x86_64. |
| 1577 |
.RE |
| 1578 |
.RS 4 |
| 1579 |
.Sp |
| 1580 |
Other keywords are ignored for Solaris compatibility. |
| 1581 |
.RE |
| 1582 |
.IP \fB\-\-gnu\-tls\-tag\fR 4 |
| 1583 |
.IX Item "--gnu-tls-tag" |
| 1584 |
.PD 0 |
| 1585 |
.IP \fB\-\-no\-gnu\-tls\-tag\fR 4 |
| 1586 |
.IX Item "--no-gnu-tls-tag" |
| 1587 |
.PD |
| 1588 |
Add \f(CW\*(C`GLIBC_ABI_GNU_TLS\*(C'\fR version tag dependency in output programs |
| 1589 |
and shared libraries when linking against glibc if input relocatable |
| 1590 |
object files call \f(CW\*(C`_\|_\|_tls_get_addr\*(C'\fR. The output will fail to load |
| 1591 |
and run at run-time against glibc which doesn't define the |
| 1592 |
\&\f(CW\*(C`GLIBC_ABI_GNU_TLS\*(C'\fR version tag. Unless disabled by the |
| 1593 |
\&\fB\-\-disable\-gnu\-tls\-tag\fR configure option at the linker build |
| 1594 |
time, when no options are specified, linker will add the |
| 1595 |
\&\f(CW\*(C`GLIBC_ABI_GNU_TLS\*(C'\fR version tag dependency if inputs have |
| 1596 |
\&\f(CW\*(C`_\|_\|_tls_get_addr\*(C'\fR call and libc.so defines the |
| 1597 |
\&\f(CW\*(C`GLIBC_ABI_GNU_TLS\*(C'\fR version tag. Supported for Linux/i386. |
| 1598 |
.IP \fB\-\-gnu2\-tls\-tag\fR 4 |
| 1599 |
.IX Item "--gnu2-tls-tag" |
| 1600 |
.PD 0 |
| 1601 |
.IP \fB\-\-no\-gnu2\-tls\-tag\fR 4 |
| 1602 |
.IX Item "--no-gnu2-tls-tag" |
| 1603 |
.PD |
| 1604 |
Add \f(CW\*(C`GLIBC_ABI_GNU2_TLS\*(C'\fR version tag dependency in output programs |
| 1605 |
and shared libraries when linking against glibc if input relocatable |
| 1606 |
object files have \f(CW\*(C`R_386_TLS_DESC_CALL\*(C'\fR or |
| 1607 |
\&\f(CW\*(C`R_X86_64_TLSDESC_CALL\*(C'\fR relocation. The output will fail to load |
| 1608 |
and run at run-time against glibc which doesn't define the |
| 1609 |
\&\f(CW\*(C`GLIBC_ABI_GNU2_TLS\*(C'\fR version tag. Unless disabled by the |
| 1610 |
\&\fB\-\-disable\-gnu2\-tls\-tag\fR configure option at the linker build |
| 1611 |
time, when no options are specified, linker will add the |
| 1612 |
\&\f(CW\*(C`GLIBC_ABI_GNU2_TLS\*(C'\fR version tag dependency if inputs have |
| 1613 |
\&\f(CW\*(C`R_386_TLS_DESC_CALL\*(C'\fR or \f(CW\*(C`R_X86_64_TLSDESC_CALL\*(C'\fR relocation |
| 1614 |
and libc.so defines the \f(CW\*(C`GLIBC_ABI_GNU2_TLS\*(C'\fR version tag. |
| 1615 |
Supported for Linux/i386 and Linux/x86_64. |
| 1616 |
.IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4 |
| 1617 |
.IX Item "-( archives -)" |
| 1618 |
.PD 0 |
| 1619 |
.IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4 |
| 1620 |
.IX Item "--start-group archives --end-group" |
| 1621 |
.PD |
| 1622 |
The \fIarchives\fR should be a list of archive files. They may be |
| 1623 |
either explicit file names, or \fB\-l\fR options. |
| 1624 |
.Sp |
| 1625 |
The specified archives are searched repeatedly until no new undefined |
| 1626 |
references are created. Normally, an archive is searched only once in |
| 1627 |
the order that it is specified on the command line. If a symbol in that |
| 1628 |
archive is needed to resolve an undefined symbol referred to by an |
| 1629 |
object in an archive that appears later on the command line, the linker |
| 1630 |
would not be able to resolve that reference. By grouping the archives, |
| 1631 |
they will all be searched repeatedly until all possible references are |
| 1632 |
resolved. |
| 1633 |
.Sp |
| 1634 |
Using this option has a significant performance cost. It is best to use |
| 1635 |
it only when there are unavoidable circular references between two or |
| 1636 |
more archives. |
| 1637 |
.IP \fB\-\-accept\-unknown\-input\-arch\fR 4 |
| 1638 |
.IX Item "--accept-unknown-input-arch" |
| 1639 |
.PD 0 |
| 1640 |
.IP \fB\-\-no\-accept\-unknown\-input\-arch\fR 4 |
| 1641 |
.IX Item "--no-accept-unknown-input-arch" |
| 1642 |
.PD |
| 1643 |
Tells the linker to accept input files whose architecture cannot be |
| 1644 |
recognised. The assumption is that the user knows what they are doing |
| 1645 |
and deliberately wants to link in these unknown input files. This was |
| 1646 |
the default behaviour of the linker, before release 2.14. The default |
| 1647 |
behaviour from release 2.14 onwards is to reject such input files, and |
| 1648 |
so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to |
| 1649 |
restore the old behaviour. |
| 1650 |
.IP \fB\-\-as\-needed\fR 4 |
| 1651 |
.IX Item "--as-needed" |
| 1652 |
.PD 0 |
| 1653 |
.IP \fB\-\-no\-as\-needed\fR 4 |
| 1654 |
.IX Item "--no-as-needed" |
| 1655 |
.PD |
| 1656 |
This option affects ELF DT_NEEDED tags for dynamic libraries mentioned |
| 1657 |
on the command line after the \fB\-\-as\-needed\fR option. Normally |
| 1658 |
the linker will add a DT_NEEDED tag for each dynamic library mentioned |
| 1659 |
on the command line, regardless of whether the library is actually |
| 1660 |
needed or not. \fB\-\-as\-needed\fR causes a DT_NEEDED tag to only be |
| 1661 |
emitted for a library that \fIat that point in the link\fR satisfies a |
| 1662 |
non-weak undefined symbol reference from a regular object file or, if |
| 1663 |
the library is not found in the DT_NEEDED lists of other needed libraries, a |
| 1664 |
non-weak undefined symbol reference from another needed dynamic library. |
| 1665 |
Object files or libraries appearing on the command line \fIafter\fR |
| 1666 |
the library in question do not affect whether the library is seen as |
| 1667 |
needed. This is similar to the rules for extraction of object files |
| 1668 |
from archives. \fB\-\-no\-as\-needed\fR restores the default behaviour. |
| 1669 |
.Sp |
| 1670 |
Note: On Linux based systems the \fB\-\-as\-needed\fR option also has |
| 1671 |
an affect on the behaviour of the \fB\-\-rpath\fR and |
| 1672 |
\&\fB\-\-rpath\-link\fR options. See the description of |
| 1673 |
\&\fB\-\-rpath\-link\fR for more details. |
| 1674 |
.IP \fB\-\-add\-needed\fR 4 |
| 1675 |
.IX Item "--add-needed" |
| 1676 |
.PD 0 |
| 1677 |
.IP \fB\-\-no\-add\-needed\fR 4 |
| 1678 |
.IX Item "--no-add-needed" |
| 1679 |
.PD |
| 1680 |
These two options have been deprecated because of the similarity of |
| 1681 |
their names to the \fB\-\-as\-needed\fR and \fB\-\-no\-as\-needed\fR |
| 1682 |
options. They have been replaced by \fB\-\-copy\-dt\-needed\-entries\fR |
| 1683 |
and \fB\-\-no\-copy\-dt\-needed\-entries\fR. |
| 1684 |
.IP "\fB\-assert\fR \fIkeyword\fR" 4 |
| 1685 |
.IX Item "-assert keyword" |
| 1686 |
This option is ignored for SunOS compatibility. |
| 1687 |
.IP \fB\-Bdynamic\fR 4 |
| 1688 |
.IX Item "-Bdynamic" |
| 1689 |
.PD 0 |
| 1690 |
.IP \fB\-dy\fR 4 |
| 1691 |
.IX Item "-dy" |
| 1692 |
.IP \fB\-call_shared\fR 4 |
| 1693 |
.IX Item "-call_shared" |
| 1694 |
.PD |
| 1695 |
Link against dynamic libraries. This is only meaningful on platforms |
| 1696 |
for which shared libraries are supported. This option is normally the |
| 1697 |
default on such platforms. The different variants of this option are |
| 1698 |
for compatibility with various systems. You may use this option |
| 1699 |
multiple times on the command line: it affects library searching for |
| 1700 |
\&\fB\-l\fR options which follow it. |
| 1701 |
.IP \fB\-Bgroup\fR 4 |
| 1702 |
.IX Item "-Bgroup" |
| 1703 |
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 |
| 1704 |
section. This causes the runtime linker to handle lookups in this |
| 1705 |
object and its dependencies to be performed only inside the group. |
| 1706 |
\&\fB\-\-unresolved\-symbols=report\-all\fR is implied. This option is |
| 1707 |
only meaningful on ELF platforms which support shared libraries. |
| 1708 |
.IP \fB\-Bstatic\fR 4 |
| 1709 |
.IX Item "-Bstatic" |
| 1710 |
.PD 0 |
| 1711 |
.IP \fB\-dn\fR 4 |
| 1712 |
.IX Item "-dn" |
| 1713 |
.IP \fB\-non_shared\fR 4 |
| 1714 |
.IX Item "-non_shared" |
| 1715 |
.IP \fB\-static\fR 4 |
| 1716 |
.IX Item "-static" |
| 1717 |
.PD |
| 1718 |
Do not link against shared libraries. This is only meaningful on |
| 1719 |
platforms for which shared libraries are supported. The different |
| 1720 |
variants of this option are for compatibility with various systems. You |
| 1721 |
may use this option multiple times on the command line: it affects |
| 1722 |
library searching for \fB\-l\fR options which follow it. This |
| 1723 |
option also implies \fB\-\-unresolved\-symbols=report\-all\fR. This |
| 1724 |
option can be used with \fB\-shared\fR. Doing so means that a |
| 1725 |
shared library is being created but that all of the library's external |
| 1726 |
references must be resolved by pulling in entries from static |
| 1727 |
libraries. |
| 1728 |
.IP \fB\-Bsymbolic\fR 4 |
| 1729 |
.IX Item "-Bsymbolic" |
| 1730 |
When creating a shared library, bind references to global symbols to the |
| 1731 |
definition within the shared library, if any. Normally, it is possible |
| 1732 |
for a program linked against a shared library to override the definition |
| 1733 |
within the shared library. This option is only meaningful on ELF |
| 1734 |
platforms which support shared libraries. |
| 1735 |
.IP \fB\-Bsymbolic\-functions\fR 4 |
| 1736 |
.IX Item "-Bsymbolic-functions" |
| 1737 |
When creating a shared library, bind references to global function |
| 1738 |
symbols to the definition within the shared library, if any. |
| 1739 |
This option is only meaningful on ELF platforms which support shared |
| 1740 |
libraries. |
| 1741 |
.IP \fB\-Bno\-symbolic\fR 4 |
| 1742 |
.IX Item "-Bno-symbolic" |
| 1743 |
This option can cancel previously specified \fB\-Bsymbolic\fR and |
| 1744 |
\&\fB\-Bsymbolic\-functions\fR. |
| 1745 |
.IP \fB\-\-dynamic\-list=\fR\fIdynamic-list-file\fR 4 |
| 1746 |
.IX Item "--dynamic-list=dynamic-list-file" |
| 1747 |
Specify the name of a dynamic list file to the linker. This is |
| 1748 |
typically used when creating shared libraries to specify a list of |
| 1749 |
global symbols whose references shouldn't be bound to the definition |
| 1750 |
within the shared library, or creating dynamically linked executables |
| 1751 |
to specify a list of symbols which should be added to the symbol table |
| 1752 |
in the executable. This option is only meaningful on ELF platforms |
| 1753 |
which support shared libraries. |
| 1754 |
.Sp |
| 1755 |
The format of the dynamic list is the same as the version node without |
| 1756 |
scope and node name. See \fBVERSION\fR for more information. |
| 1757 |
.IP \fB\-\-dynamic\-list\-data\fR 4 |
| 1758 |
.IX Item "--dynamic-list-data" |
| 1759 |
Include all global data symbols to the dynamic list. |
| 1760 |
.IP \fB\-\-dynamic\-list\-cpp\-new\fR 4 |
| 1761 |
.IX Item "--dynamic-list-cpp-new" |
| 1762 |
Provide the builtin dynamic list for C++ operator new and delete. It |
| 1763 |
is mainly useful for building shared libstdc++. |
| 1764 |
.IP \fB\-\-dynamic\-list\-cpp\-typeinfo\fR 4 |
| 1765 |
.IX Item "--dynamic-list-cpp-typeinfo" |
| 1766 |
Provide the builtin dynamic list for C++ runtime type identification. |
| 1767 |
.IP \fB\-\-check\-sections\fR 4 |
| 1768 |
.IX Item "--check-sections" |
| 1769 |
.PD 0 |
| 1770 |
.IP \fB\-\-no\-check\-sections\fR 4 |
| 1771 |
.IX Item "--no-check-sections" |
| 1772 |
.PD |
| 1773 |
Asks the linker \fInot\fR to check section addresses after they have |
| 1774 |
been assigned to see if there are any overlaps. Normally the linker will |
| 1775 |
perform this check, and if it finds any overlaps it will produce |
| 1776 |
suitable error messages. The linker does know about, and does make |
| 1777 |
allowances for sections in overlays. The default behaviour can be |
| 1778 |
restored by using the command-line switch \fB\-\-check\-sections\fR. |
| 1779 |
Section overlap is not usually checked for relocatable links. You can |
| 1780 |
force checking in that case by using the \fB\-\-check\-sections\fR |
| 1781 |
option. |
| 1782 |
.IP \fB\-\-copy\-dt\-needed\-entries\fR 4 |
| 1783 |
.IX Item "--copy-dt-needed-entries" |
| 1784 |
.PD 0 |
| 1785 |
.IP \fB\-\-no\-copy\-dt\-needed\-entries\fR 4 |
| 1786 |
.IX Item "--no-copy-dt-needed-entries" |
| 1787 |
.PD |
| 1788 |
This option affects the treatment of dynamic libraries referred to |
| 1789 |
by DT_NEEDED tags \fIinside\fR ELF dynamic libraries mentioned on the |
| 1790 |
command line. Normally the linker won't add a DT_NEEDED tag to the |
| 1791 |
output binary for each library mentioned in a DT_NEEDED tag in an |
| 1792 |
input dynamic library. With \fB\-\-copy\-dt\-needed\-entries\fR |
| 1793 |
specified on the command line however any dynamic libraries that |
| 1794 |
follow it will have their DT_NEEDED entries added. The default |
| 1795 |
behaviour can be restored with \fB\-\-no\-copy\-dt\-needed\-entries\fR. |
| 1796 |
.Sp |
| 1797 |
This option also has an effect on the resolution of symbols in dynamic |
| 1798 |
libraries. With \fB\-\-copy\-dt\-needed\-entries\fR dynamic libraries |
| 1799 |
mentioned on the command line will be recursively searched, following |
| 1800 |
their DT_NEEDED tags to other libraries, in order to resolve symbols |
| 1801 |
required by the output binary. With the default setting however |
| 1802 |
the searching of dynamic libraries that follow it will stop with the |
| 1803 |
dynamic library itself. No DT_NEEDED links will be traversed to resolve |
| 1804 |
symbols. |
| 1805 |
.IP \fB\-\-cref\fR 4 |
| 1806 |
.IX Item "--cref" |
| 1807 |
Output a cross reference table. If a linker map file is being |
| 1808 |
generated, the cross reference table is printed to the map file. |
| 1809 |
Otherwise, it is printed on the standard output. |
| 1810 |
.Sp |
| 1811 |
The format of the table is intentionally simple, so that it may be |
| 1812 |
easily processed by a script if necessary. The symbols are printed out, |
| 1813 |
sorted by name. For each symbol, a list of file names is given. If the |
| 1814 |
symbol is defined, the first file listed is the location of the |
| 1815 |
definition. If the symbol is defined as a common value then any files |
| 1816 |
where this happens appear next. Finally any files that reference the |
| 1817 |
symbol are listed. |
| 1818 |
.IP \fB\-\-ctf\-variables\fR 4 |
| 1819 |
.IX Item "--ctf-variables" |
| 1820 |
.PD 0 |
| 1821 |
.IP \fB\-\-no\-ctf\-variables\fR 4 |
| 1822 |
.IX Item "--no-ctf-variables" |
| 1823 |
.PD |
| 1824 |
The CTF debuginfo format supports a section which encodes the names and |
| 1825 |
types of variables found in the program which do not appear in any symbol |
| 1826 |
table. These variables clearly cannot be looked up by address by |
| 1827 |
conventional debuggers, so the space used for their types and names is |
| 1828 |
usually wasted: the types are usually small but the names are often not. |
| 1829 |
\&\fB\-\-ctf\-variables\fR causes the generation of such a section. |
| 1830 |
The default behaviour can be restored with \fB\-\-no\-ctf\-variables\fR. |
| 1831 |
.IP \fB\-\-ctf\-share\-types=\fR\fImethod\fR 4 |
| 1832 |
.IX Item "--ctf-share-types=method" |
| 1833 |
Adjust the method used to share types between translation units in CTF. |
| 1834 |
.RS 4 |
| 1835 |
.IP \fBshare-unconflicted\fR 4 |
| 1836 |
.IX Item "share-unconflicted" |
| 1837 |
Put all types that do not have ambiguous definitions into the shared dictionary, |
| 1838 |
where debuggers can easily access them, even if they only occur in one |
| 1839 |
translation unit. This is the default. |
| 1840 |
.IP \fBshare-duplicated\fR 4 |
| 1841 |
.IX Item "share-duplicated" |
| 1842 |
Put only types that occur in multiple translation units into the shared |
| 1843 |
dictionary: types with only one definition go into per-translation-unit |
| 1844 |
dictionaries. Types with ambiguous definitions in multiple translation units |
| 1845 |
always go into per-translation-unit dictionaries. This tends to make the CTF |
| 1846 |
larger, but may reduce the amount of CTF in the shared dictionary. For very |
| 1847 |
large projects this may speed up opening the CTF and save memory in the CTF |
| 1848 |
consumer at runtime. |
| 1849 |
.RE |
| 1850 |
.RS 4 |
| 1851 |
.RE |
| 1852 |
.IP \fB\-\-no\-define\-common\fR 4 |
| 1853 |
.IX Item "--no-define-common" |
| 1854 |
This option inhibits the assignment of addresses to common symbols. |
| 1855 |
The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect. |
| 1856 |
.Sp |
| 1857 |
The \fB\-\-no\-define\-common\fR option allows decoupling |
| 1858 |
the decision to assign addresses to Common symbols from the choice |
| 1859 |
of the output file type; otherwise a non-Relocatable output type |
| 1860 |
forces assigning addresses to Common symbols. |
| 1861 |
Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced |
| 1862 |
from a shared library to be assigned addresses only in the main program. |
| 1863 |
This eliminates the unused duplicate space in the shared library, |
| 1864 |
and also prevents any possible confusion over resolving to the wrong |
| 1865 |
duplicate when there are many dynamic modules with specialized search |
| 1866 |
paths for runtime symbol resolution. |
| 1867 |
.IP \fB\-\-force\-group\-allocation\fR 4 |
| 1868 |
.IX Item "--force-group-allocation" |
| 1869 |
This option causes the linker to place section group members like |
| 1870 |
normal input sections, and to delete the section groups. This is the |
| 1871 |
default behaviour for a final link but this option can be used to |
| 1872 |
change the behaviour of a relocatable link (\fB\-r\fR). The script |
| 1873 |
command \f(CW\*(C`FORCE_GROUP_ALLOCATION\*(C'\fR has the same |
| 1874 |
effect. |
| 1875 |
.IP \fB\-\-defsym=\fR\fIsymbol\fR\fB=\fR\fIexpression\fR 4 |
| 1876 |
.IX Item "--defsym=symbol=expression" |
| 1877 |
Create a global symbol in the output file, containing the absolute |
| 1878 |
address given by \fIexpression\fR. You may use this option as many |
| 1879 |
times as necessary to define multiple symbols in the command line. A |
| 1880 |
limited form of arithmetic is supported for the \fIexpression\fR in this |
| 1881 |
context: you may give a hexadecimal constant or the name of an existing |
| 1882 |
symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal |
| 1883 |
constants or symbols. If you need more elaborate expressions, consider |
| 1884 |
using the linker command language from a script. |
| 1885 |
\&\fINote:\fR there should be no white space between \fIsymbol\fR, the |
| 1886 |
equals sign ("\fB=\fR"), and \fIexpression\fR. |
| 1887 |
.Sp |
| 1888 |
The linker processes \fB\-\-defsym\fR arguments and \fB\-T\fR arguments |
| 1889 |
in order, placing \fB\-\-defsym\fR before \fB\-T\fR will define the |
| 1890 |
symbol before the linker script from \fB\-T\fR is processed, while |
| 1891 |
placing \fB\-\-defsym\fR after \fB\-T\fR will define the symbol after |
| 1892 |
the linker script has been processed. This difference has |
| 1893 |
consequences for expressions within the linker script that use the |
| 1894 |
\&\fB\-\-defsym\fR symbols, which order is correct will depend on what |
| 1895 |
you are trying to achieve. |
| 1896 |
.IP \fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR 4 |
| 1897 |
.IX Item "--demangle[=style]" |
| 1898 |
.PD 0 |
| 1899 |
.IP \fB\-\-no\-demangle\fR 4 |
| 1900 |
.IX Item "--no-demangle" |
| 1901 |
.PD |
| 1902 |
These options control whether to demangle symbol names in error messages |
| 1903 |
and other output. When the linker is told to demangle, it tries to |
| 1904 |
present symbol names in a readable fashion: it strips leading |
| 1905 |
underscores if they are used by the object file format, and converts C++ |
| 1906 |
mangled symbol names into user readable names. Different compilers have |
| 1907 |
different mangling styles. The optional demangling style argument can be used |
| 1908 |
to choose an appropriate demangling style for your compiler. The linker will |
| 1909 |
demangle by default unless the environment variable \fBCOLLECT_NO_DEMANGLE\fR |
| 1910 |
is set. These options may be used to override the default. |
| 1911 |
.IP \fB\-I\fR\fIfile\fR 4 |
| 1912 |
.IX Item "-Ifile" |
| 1913 |
.PD 0 |
| 1914 |
.IP \fB\-\-dynamic\-linker=\fR\fIfile\fR 4 |
| 1915 |
.IX Item "--dynamic-linker=file" |
| 1916 |
.PD |
| 1917 |
Set the name of the dynamic linker. This is only meaningful when |
| 1918 |
generating dynamically linked ELF executables. The default dynamic |
| 1919 |
linker is normally correct; don't use this unless you know what you are |
| 1920 |
doing. |
| 1921 |
.IP \fB\-\-no\-dynamic\-linker\fR 4 |
| 1922 |
.IX Item "--no-dynamic-linker" |
| 1923 |
When producing an executable file, omit the request for a dynamic |
| 1924 |
linker to be used at load-time. This is only meaningful for ELF |
| 1925 |
executables that contain dynamic relocations, and usually requires |
| 1926 |
entry point code that is capable of processing these relocations. |
| 1927 |
.IP \fB\-\-embedded\-relocs\fR 4 |
| 1928 |
.IX Item "--embedded-relocs" |
| 1929 |
This option is similar to the \fB\-\-emit\-relocs\fR option except |
| 1930 |
that the relocs are stored in a target-specific section. This option |
| 1931 |
is only supported by the \fBBFIN\fR, \fBCR16\fR and \fIM68K\fR |
| 1932 |
targets. |
| 1933 |
.IP \fB\-\-disable\-multiple\-abs\-defs\fR 4 |
| 1934 |
.IX Item "--disable-multiple-abs-defs" |
| 1935 |
Do not allow multiple definitions with symbols included |
| 1936 |
in filename invoked by \-R or \-\-just\-symbols |
| 1937 |
.IP \fB\-\-fatal\-warnings\fR 4 |
| 1938 |
.IX Item "--fatal-warnings" |
| 1939 |
.PD 0 |
| 1940 |
.IP \fB\-\-no\-fatal\-warnings\fR 4 |
| 1941 |
.IX Item "--no-fatal-warnings" |
| 1942 |
.PD |
| 1943 |
Treat all warnings as errors. The default behaviour can be restored |
| 1944 |
with the option \fB\-\-no\-fatal\-warnings\fR. |
| 1945 |
.IP \fB\-w\fR 4 |
| 1946 |
.IX Item "-w" |
| 1947 |
.PD 0 |
| 1948 |
.IP \fB\-\-no\-warnings\fR 4 |
| 1949 |
.IX Item "--no-warnings" |
| 1950 |
.PD |
| 1951 |
Do not display any warning or error messages. This overrides |
| 1952 |
\&\fB\-\-fatal\-warnings\fR if it has been enabled. This option can be |
| 1953 |
used when it is known that the output binary will not work, but there |
| 1954 |
is still a need to create it. |
| 1955 |
.IP \fB\-\-force\-exe\-suffix\fR 4 |
| 1956 |
.IX Item "--force-exe-suffix" |
| 1957 |
Make sure that an output file has a .exe suffix. |
| 1958 |
.Sp |
| 1959 |
If a successfully built fully linked output file does not have a |
| 1960 |
\&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy |
| 1961 |
the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This |
| 1962 |
option is useful when using unmodified Unix makefiles on a Microsoft |
| 1963 |
Windows host, since some versions of Windows won't run an image unless |
| 1964 |
it ends in a \f(CW\*(C`.exe\*(C'\fR suffix. |
| 1965 |
.IP \fB\-\-gc\-sections\fR 4 |
| 1966 |
.IX Item "--gc-sections" |
| 1967 |
.PD 0 |
| 1968 |
.IP \fB\-\-no\-gc\-sections\fR 4 |
| 1969 |
.IX Item "--no-gc-sections" |
| 1970 |
.PD |
| 1971 |
Enable garbage collection of unused input sections. It is ignored on |
| 1972 |
targets that do not support this option. The default behaviour (of not |
| 1973 |
performing this garbage collection) can be restored by specifying |
| 1974 |
\&\fB\-\-no\-gc\-sections\fR on the command line. Note that garbage |
| 1975 |
collection for COFF and PE format targets is supported, but the |
| 1976 |
implementation is currently considered to be experimental. |
| 1977 |
.Sp |
| 1978 |
\&\fB\-\-gc\-sections\fR decides which input sections are used by |
| 1979 |
examining symbols and relocations. The section containing the entry |
| 1980 |
symbol and all sections containing symbols undefined on the |
| 1981 |
command-line will be kept, as will sections containing symbols |
| 1982 |
referenced by dynamic objects. Note that when building shared |
| 1983 |
libraries, the linker must assume that any visible symbol is |
| 1984 |
referenced. Once this initial set of sections has been determined, |
| 1985 |
the linker recursively marks as used any section referenced by their |
| 1986 |
relocations. See \fB\-\-entry\fR, \fB\-\-undefined\fR, and |
| 1987 |
\&\fB\-\-gc\-keep\-exported\fR. |
| 1988 |
.Sp |
| 1989 |
This option can be set when doing a partial link (enabled with option |
| 1990 |
\&\fB\-r\fR). In this case the root of symbols kept must be explicitly |
| 1991 |
specified either by one of the options \fB\-\-entry\fR, |
| 1992 |
\&\fB\-\-undefined\fR, or \fB\-\-gc\-keep\-exported\fR or by a \f(CW\*(C`ENTRY\*(C'\fR |
| 1993 |
command in the linker script. |
| 1994 |
.Sp |
| 1995 |
As a GNU extension, ELF input sections marked with the |
| 1996 |
\&\f(CW\*(C`SHF_GNU_RETAIN\*(C'\fR flag will not be garbage collected. |
| 1997 |
.IP \fB\-\-print\-gc\-sections\fR 4 |
| 1998 |
.IX Item "--print-gc-sections" |
| 1999 |
.PD 0 |
| 2000 |
.IP \fB\-\-no\-print\-gc\-sections\fR 4 |
| 2001 |
.IX Item "--no-print-gc-sections" |
| 2002 |
.PD |
| 2003 |
List all sections removed by garbage collection. The listing is |
| 2004 |
printed on stderr. This option is only effective if garbage |
| 2005 |
collection has been enabled via the \fB\-\-gc\-sections\fR) option. The |
| 2006 |
default behaviour (of not listing the sections that are removed) can |
| 2007 |
be restored by specifying \fB\-\-no\-print\-gc\-sections\fR on the command |
| 2008 |
line. |
| 2009 |
.IP \fB\-\-gc\-keep\-exported\fR 4 |
| 2010 |
.IX Item "--gc-keep-exported" |
| 2011 |
When \fB\-\-gc\-sections\fR is enabled, this option prevents garbage |
| 2012 |
collection of unused input sections that contain global symbols having |
| 2013 |
default or protected visibility. This option is intended to be used for |
| 2014 |
executables where unreferenced sections would otherwise be garbage |
| 2015 |
collected regardless of the external visibility of contained symbols. |
| 2016 |
Note that this option has no effect when linking shared objects since |
| 2017 |
it is already the default behaviour. This option is only supported for |
| 2018 |
ELF format targets. |
| 2019 |
.IP \fB\-\-print\-output\-format\fR 4 |
| 2020 |
.IX Item "--print-output-format" |
| 2021 |
Print the name of the default output format (perhaps influenced by |
| 2022 |
other command-line options). This is the string that would appear |
| 2023 |
in an \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR linker script command. |
| 2024 |
.IP \fB\-\-print\-memory\-usage\fR 4 |
| 2025 |
.IX Item "--print-memory-usage" |
| 2026 |
Print used size, total size and used size of memory regions created with |
| 2027 |
the \fBMEMORY\fR command. This is useful on embedded targets to have a |
| 2028 |
quick view of amount of free memory. The format of the output has one |
| 2029 |
headline and one line per region. It is both human readable and easily |
| 2030 |
parsable by tools. Here is an example of an output: |
| 2031 |
.Sp |
| 2032 |
.Vb 3 |
| 2033 |
\& Memory region Used Size Region Size %age Used |
| 2034 |
\& ROM: 256 KB 1 MB 25.00% |
| 2035 |
\& RAM: 32 B 2 GB 0.00% |
| 2036 |
.Ve |
| 2037 |
.Sp |
| 2038 |
Note: if you want to find out about the memory usage of the linker |
| 2039 |
itself, then the \fB\-\-stats\fR option will do this. |
| 2040 |
.IP \fB\-\-help\fR 4 |
| 2041 |
.IX Item "--help" |
| 2042 |
Print a summary of the command-line options on the standard output and exit. |
| 2043 |
.IP \fB\-\-target\-help\fR 4 |
| 2044 |
.IX Item "--target-help" |
| 2045 |
Print a summary of all target-specific options on the standard output and exit. |
| 2046 |
.IP \fB\-Map=\fR\fImapfile\fR 4 |
| 2047 |
.IX Item "-Map=mapfile" |
| 2048 |
Print a link map to the file \fImapfile\fR. See the description of the |
| 2049 |
\&\fB\-M\fR option, above. If \fImapfile\fR is just the character |
| 2050 |
\&\f(CW\*(C`\-\*(C'\fR then the map will be written to stdout. |
| 2051 |
.Sp |
| 2052 |
Specifying a directory as \fImapfile\fR causes the linker map to be |
| 2053 |
written as a file inside the directory. Normally name of the file |
| 2054 |
inside the directory is computed as the basename of the \fIoutput\fR |
| 2055 |
file with \f(CW\*(C`.map\*(C'\fR appended. If however the special character |
| 2056 |
\&\f(CW\*(C`%\*(C'\fR is used then this will be replaced by the full path of the |
| 2057 |
output file. Additionally if there are any characters after the |
| 2058 |
\&\fI%\fR symbol then \f(CW\*(C`.map\*(C'\fR will no longer be appended. |
| 2059 |
.Sp |
| 2060 |
.Vb 10 |
| 2061 |
\& \-o foo.exe \-Map=bar [Creates ./bar] |
| 2062 |
\& \-o ../dir/foo.exe \-Map=bar [Creates ./bar] |
| 2063 |
\& \-o foo.exe \-Map=../dir [Creates ../dir/foo.exe.map] |
| 2064 |
\& \-o ../dir2/foo.exe \-Map=../dir [Creates ../dir/foo.exe.map] |
| 2065 |
\& \-o foo.exe \-Map=% [Creates ./foo.exe.map] |
| 2066 |
\& \-o ../dir/foo.exe \-Map=% [Creates ../dir/foo.exe.map] |
| 2067 |
\& \-o foo.exe \-Map=%.bar [Creates ./foo.exe.bar] |
| 2068 |
\& \-o ../dir/foo.exe \-Map=%.bar [Creates ../dir/foo.exe.bar] |
| 2069 |
\& \-o ../dir2/foo.exe \-Map=../dir/% [Creates ../dir/../dir2/foo.exe.map] |
| 2070 |
\& \-o ../dir2/foo.exe \-Map=../dir/%.bar [Creates ../dir/../dir2/foo.exe.bar] |
| 2071 |
.Ve |
| 2072 |
.Sp |
| 2073 |
It is an error to specify more than one \f(CW\*(C`%\*(C'\fR character. |
| 2074 |
.Sp |
| 2075 |
If the map file already exists then it will be overwritten by this |
| 2076 |
operation. |
| 2077 |
.IP \fB\-\-no\-keep\-memory\fR 4 |
| 2078 |
.IX Item "--no-keep-memory" |
| 2079 |
\&\fBld\fR normally optimizes for speed over memory usage by caching the |
| 2080 |
symbol tables of input files in memory. This option tells \fBld\fR to |
| 2081 |
instead optimize for memory usage, by rereading the symbol tables as |
| 2082 |
necessary. This may be required if \fBld\fR runs out of memory space |
| 2083 |
while linking a large executable. |
| 2084 |
.IP \fB\-\-no\-undefined\fR 4 |
| 2085 |
.IX Item "--no-undefined" |
| 2086 |
.PD 0 |
| 2087 |
.IP "\fB\-z defs\fR" 4 |
| 2088 |
.IX Item "-z defs" |
| 2089 |
.PD |
| 2090 |
Report unresolved symbol references from regular object files. This |
| 2091 |
is done even if the linker is creating a non-symbolic shared library. |
| 2092 |
The switch \fB\-\-[no\-]allow\-shlib\-undefined\fR controls the |
| 2093 |
behaviour for reporting unresolved references found in shared |
| 2094 |
libraries being linked in. |
| 2095 |
.Sp |
| 2096 |
The effects of this option can be reverted by using \f(CW\*(C`\-z undefs\*(C'\fR. |
| 2097 |
.IP \fB\-\-allow\-multiple\-definition\fR 4 |
| 2098 |
.IX Item "--allow-multiple-definition" |
| 2099 |
.PD 0 |
| 2100 |
.IP "\fB\-z muldefs\fR" 4 |
| 2101 |
.IX Item "-z muldefs" |
| 2102 |
.PD |
| 2103 |
Normally when a symbol is defined multiple times, the linker will |
| 2104 |
report a fatal error. These options allow multiple definitions and the |
| 2105 |
first definition will be used. |
| 2106 |
.IP \fB\-\-allow\-shlib\-undefined\fR 4 |
| 2107 |
.IX Item "--allow-shlib-undefined" |
| 2108 |
.PD 0 |
| 2109 |
.IP \fB\-\-no\-allow\-shlib\-undefined\fR 4 |
| 2110 |
.IX Item "--no-allow-shlib-undefined" |
| 2111 |
.PD |
| 2112 |
Allows or disallows undefined symbols in shared libraries. |
| 2113 |
This switch is similar to \fB\-\-no\-undefined\fR except that it |
| 2114 |
determines the behaviour when the undefined symbols are in a |
| 2115 |
shared library rather than a regular object file. It does not affect |
| 2116 |
how undefined symbols in regular object files are handled. |
| 2117 |
.Sp |
| 2118 |
The default behaviour is to report errors for any undefined symbols |
| 2119 |
referenced in shared libraries if the linker is being used to create |
| 2120 |
an executable, but to allow them if the linker is being used to create |
| 2121 |
a shared library. |
| 2122 |
.Sp |
| 2123 |
The reasons for allowing undefined symbol references in shared |
| 2124 |
libraries specified at link time are that: |
| 2125 |
.RS 4 |
| 2126 |
.IP \(bu 4 |
| 2127 |
A shared library specified at link time may not be the same as the one |
| 2128 |
that is available at load time, so the symbol might actually be |
| 2129 |
resolvable at load time. |
| 2130 |
.IP \(bu 4 |
| 2131 |
There are some operating systems, eg BeOS and HPPA, where undefined |
| 2132 |
symbols in shared libraries are normal. |
| 2133 |
.Sp |
| 2134 |
The BeOS kernel for example patches shared libraries at load time to |
| 2135 |
select whichever function is most appropriate for the current |
| 2136 |
architecture. This is used, for example, to dynamically select an |
| 2137 |
appropriate memset function. |
| 2138 |
.RE |
| 2139 |
.RS 4 |
| 2140 |
.RE |
| 2141 |
.IP \fB\-\-error\-handling\-script=\fR\fIscriptname\fR 4 |
| 2142 |
.IX Item "--error-handling-script=scriptname" |
| 2143 |
If this option is provided then the linker will invoke |
| 2144 |
\&\fIscriptname\fR whenever an error is encountered. Currently however |
| 2145 |
only two kinds of error are supported: missing symbols and missing |
| 2146 |
libraries. Two arguments will be passed to script: the keyword |
| 2147 |
"undefined-symbol" or `missing\-lib" and the \fIname\fR of the |
| 2148 |
undefined symbol or missing library. The intention is that the script |
| 2149 |
will provide suggestions to the user as to where the symbol or library |
| 2150 |
might be found. After the script has finished then the normal linker |
| 2151 |
error message will be displayed. |
| 2152 |
.Sp |
| 2153 |
The availability of this option is controlled by a configure time |
| 2154 |
switch, so it may not be present in specific implementations. |
| 2155 |
.IP \fB\-\-no\-undefined\-version\fR 4 |
| 2156 |
.IX Item "--no-undefined-version" |
| 2157 |
Normally when a symbol has an undefined version, the linker will ignore |
| 2158 |
it. This option disallows symbols with undefined version and a fatal error |
| 2159 |
will be issued instead. |
| 2160 |
.IP \fB\-\-default\-symver\fR 4 |
| 2161 |
.IX Item "--default-symver" |
| 2162 |
Create and use a default symbol version (the soname) for unversioned |
| 2163 |
exported symbols. |
| 2164 |
.IP \fB\-\-default\-imported\-symver\fR 4 |
| 2165 |
.IX Item "--default-imported-symver" |
| 2166 |
Create and use a default symbol version (the soname) for unversioned |
| 2167 |
imported symbols. |
| 2168 |
.IP \fB\-\-no\-warn\-mismatch\fR 4 |
| 2169 |
.IX Item "--no-warn-mismatch" |
| 2170 |
Normally \fBld\fR will give an error if you try to link together input |
| 2171 |
files that are mismatched for some reason, perhaps because they have |
| 2172 |
been compiled for different processors or for different endiannesses. |
| 2173 |
This option tells \fBld\fR that it should silently permit such possible |
| 2174 |
errors. This option should only be used with care, in cases when you |
| 2175 |
have taken some special action that ensures that the linker errors are |
| 2176 |
inappropriate. |
| 2177 |
.IP \fB\-\-no\-warn\-search\-mismatch\fR 4 |
| 2178 |
.IX Item "--no-warn-search-mismatch" |
| 2179 |
Normally \fBld\fR will give a warning if it finds an incompatible |
| 2180 |
library during a library search. This option silences the warning. |
| 2181 |
.IP \fB\-\-no\-whole\-archive\fR 4 |
| 2182 |
.IX Item "--no-whole-archive" |
| 2183 |
Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent |
| 2184 |
archive files. |
| 2185 |
.IP \fB\-\-noinhibit\-exec\fR 4 |
| 2186 |
.IX Item "--noinhibit-exec" |
| 2187 |
Retain the executable output file whenever it is still usable. |
| 2188 |
Normally, the linker will not produce an output file if it encounters |
| 2189 |
errors during the link process; it exits without writing an output file |
| 2190 |
when it issues any error whatsoever. |
| 2191 |
.IP \fB\-nostdlib\fR 4 |
| 2192 |
.IX Item "-nostdlib" |
| 2193 |
Only search library directories explicitly specified on the |
| 2194 |
command line. Library directories specified in linker scripts |
| 2195 |
(including linker scripts specified on the command line) are ignored. |
| 2196 |
.IP \fB\-\-oformat=\fR\fIoutput-format\fR 4 |
| 2197 |
.IX Item "--oformat=output-format" |
| 2198 |
\&\fBld\fR may be configured to support more than one kind of object |
| 2199 |
file. If your \fBld\fR is configured this way, you can use the |
| 2200 |
\&\fB\-\-oformat\fR option to specify the binary format for the output |
| 2201 |
object file. Even when \fBld\fR is configured to support alternative |
| 2202 |
object formats, you don't usually need to specify this, as \fBld\fR |
| 2203 |
should be configured to produce as a default output format the most |
| 2204 |
usual format on each machine. \fIoutput-format\fR is a text string, the |
| 2205 |
name of a particular format supported by the BFD libraries. (You can |
| 2206 |
list the available binary formats with \fBobjdump \-i\fR.) The script |
| 2207 |
command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but |
| 2208 |
this option overrides it. |
| 2209 |
.IP "\fB\-\-out\-implib\fR \fIfile\fR" 4 |
| 2210 |
.IX Item "--out-implib file" |
| 2211 |
Create an import library in \fIfile\fR corresponding to the executable |
| 2212 |
the linker is generating (eg. a DLL or ELF program). This import |
| 2213 |
library (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR for DLLs) |
| 2214 |
may be used to link clients against the generated executable; this |
| 2215 |
behaviour makes it possible to skip a separate import library creation |
| 2216 |
step (eg. \f(CW\*(C`dlltool\*(C'\fR for DLLs). This option is only available for |
| 2217 |
the i386 PE and ELF targetted ports of the linker. |
| 2218 |
.IP \fB\-pie\fR 4 |
| 2219 |
.IX Item "-pie" |
| 2220 |
.PD 0 |
| 2221 |
.IP \fB\-\-pic\-executable\fR 4 |
| 2222 |
.IX Item "--pic-executable" |
| 2223 |
.PD |
| 2224 |
Create a position independent executable. This is currently only |
| 2225 |
supported on ELF platforms. Position independent executables are |
| 2226 |
relocated by the dynamic linker to the virtual address the OS chooses |
| 2227 |
for them, which can vary between invocations. They are marked ET_DYN |
| 2228 |
in the ELF file header, but differ from shared libraries in a number |
| 2229 |
of ways. In particular, defined symbols in a PIE by default can not |
| 2230 |
be overridden by another object as they can be in a shared library. |
| 2231 |
.IP \fB\-no\-pie\fR 4 |
| 2232 |
.IX Item "-no-pie" |
| 2233 |
Create a position dependent executable. This is the default. |
| 2234 |
.IP \fB\-qmagic\fR 4 |
| 2235 |
.IX Item "-qmagic" |
| 2236 |
This option is ignored for Linux compatibility. |
| 2237 |
.IP \fB\-Qy\fR 4 |
| 2238 |
.IX Item "-Qy" |
| 2239 |
This option is ignored for SVR4 compatibility. |
| 2240 |
.IP \fB\-\-relax\fR 4 |
| 2241 |
.IX Item "--relax" |
| 2242 |
.PD 0 |
| 2243 |
.IP \fB\-\-no\-relax\fR 4 |
| 2244 |
.IX Item "--no-relax" |
| 2245 |
.PD |
| 2246 |
An option with machine dependent effects. |
| 2247 |
This option is only supported on a few targets. |
| 2248 |
.Sp |
| 2249 |
On some platforms the \fB\-\-relax\fR option performs target specific, |
| 2250 |
global optimizations that become possible when the linker resolves |
| 2251 |
addressing in the program, such as relaxing address modes, |
| 2252 |
synthesizing new instructions, selecting shorter version of current |
| 2253 |
instructions, and combining constant values. |
| 2254 |
.Sp |
| 2255 |
On some platforms these link time global optimizations may make symbolic |
| 2256 |
debugging of the resulting executable impossible. |
| 2257 |
This is known to be the case for the Matsushita MN10200 and MN10300 |
| 2258 |
family of processors. |
| 2259 |
.Sp |
| 2260 |
On platforms where the feature is supported, the option |
| 2261 |
\&\fB\-\-no\-relax\fR will disable it. |
| 2262 |
.Sp |
| 2263 |
On platforms where the feature is not supported, both \fB\-\-relax\fR |
| 2264 |
and \fB\-\-no\-relax\fR are accepted, but ignored. |
| 2265 |
.IP \fB\-\-retain\-symbols\-file=\fR\fIfilename\fR 4 |
| 2266 |
.IX Item "--retain-symbols-file=filename" |
| 2267 |
Retain \fIonly\fR the symbols listed in the file \fIfilename\fR, |
| 2268 |
discarding all others. \fIfilename\fR is simply a flat file, with one |
| 2269 |
symbol name per line. This option is especially useful in environments |
| 2270 |
(such as VxWorks) |
| 2271 |
where a large global symbol table is accumulated gradually, to conserve |
| 2272 |
run-time memory. |
| 2273 |
.Sp |
| 2274 |
\&\fB\-\-retain\-symbols\-file\fR does \fInot\fR discard undefined symbols, |
| 2275 |
or symbols needed for relocations. |
| 2276 |
.Sp |
| 2277 |
You may only specify \fB\-\-retain\-symbols\-file\fR once in the command |
| 2278 |
line. It overrides \fB\-s\fR and \fB\-S\fR. |
| 2279 |
.IP \fB\-rpath=\fR\fIdir\fR 4 |
| 2280 |
.IX Item "-rpath=dir" |
| 2281 |
Add a directory to the runtime library search path. This is used when |
| 2282 |
linking an ELF executable with shared objects. All \fB\-rpath\fR |
| 2283 |
arguments are concatenated and passed to the runtime linker, which uses |
| 2284 |
them to locate shared objects at runtime. |
| 2285 |
.Sp |
| 2286 |
The \fB\-rpath\fR option is also used when locating shared objects which |
| 2287 |
are needed by shared objects explicitly included in the link; see the |
| 2288 |
description of the \fB\-rpath\-link\fR option. Searching \fB\-rpath\fR |
| 2289 |
in this way is only supported by native linkers and cross linkers which |
| 2290 |
have been configured with the \fB\-\-with\-sysroot\fR option. |
| 2291 |
.Sp |
| 2292 |
If \fB\-rpath\fR is not used when linking an ELF executable, the |
| 2293 |
contents of the environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it |
| 2294 |
is defined. |
| 2295 |
.Sp |
| 2296 |
The \fB\-rpath\fR option may also be used on SunOS. By default, on |
| 2297 |
SunOS, the linker will form a runtime search path out of all the |
| 2298 |
\&\fB\-L\fR options it is given. If a \fB\-rpath\fR option is used, the |
| 2299 |
runtime search path will be formed exclusively using the \fB\-rpath\fR |
| 2300 |
options, ignoring the \fB\-L\fR options. This can be useful when using |
| 2301 |
gcc, which adds many \fB\-L\fR options which may be on NFS mounted |
| 2302 |
file systems. |
| 2303 |
.Sp |
| 2304 |
For compatibility with other ELF linkers, if the \fB\-R\fR option is |
| 2305 |
followed by a directory name, rather than a file name, it is treated as |
| 2306 |
the \fB\-rpath\fR option. |
| 2307 |
.IP \fB\-rpath\-link=\fR\fIdir\fR 4 |
| 2308 |
.IX Item "-rpath-link=dir" |
| 2309 |
When using ELF or SunOS, one shared library may require another. This |
| 2310 |
happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one |
| 2311 |
of the input files. |
| 2312 |
.Sp |
| 2313 |
When the linker encounters such a dependency when doing a non-shared, |
| 2314 |
non-relocatable link, it will automatically try to locate the required |
| 2315 |
shared library and include it in the link, if it is not included |
| 2316 |
explicitly. In such a case, several directories are searched as |
| 2317 |
described below. The \fB\-rpath\-link\fR option specifies the first |
| 2318 |
set of directories to search. This option may specify a sequence of |
| 2319 |
directory names either by providing a list of names separated by |
| 2320 |
colons, or by appearing multiple times. |
| 2321 |
.Sp |
| 2322 |
The tokens \fR\f(CI$ORIGIN\fR\fI\fR and \fI\fR\f(CI$LIB\fR\fI\fR can appear in these search |
| 2323 |
directories. They will be replaced by the full path to the directory |
| 2324 |
containing the program or shared object in the case of \fI\fR\f(CI$ORIGIN\fR\fI\fR |
| 2325 |
and either \fBlib\fR \- for 32\-bit binaries \- or \fBlib64\fR \- for |
| 2326 |
64\-bit binaries \- in the case of \fI\fR\f(CI$LIB\fR\fI\fR. |
| 2327 |
.Sp |
| 2328 |
The alternative form of these tokens \- \fI${ORIGIN}\fR and |
| 2329 |
\&\fI${LIB}\fR can also be used. The token \fR\f(CI$PLATFORM\fR\fI\fR is not |
| 2330 |
supported. |
| 2331 |
.Sp |
| 2332 |
The \fB\-\-rpath\-link\fR option should be used with caution as it |
| 2333 |
overrides the search path that may have been hard compiled into a |
| 2334 |
shared library. In such a case it is possible to unintentionally use |
| 2335 |
a different search path than the runtime linker would have used. |
| 2336 |
.Sp |
| 2337 |
When additional shared libraries are required, the linker will search |
| 2338 |
directories in the order listed below in order to find them. Note |
| 2339 |
however that this only applies to additional libraries needed to |
| 2340 |
satisfy already included shared libraries. It does \fInot\fR |
| 2341 |
apply to libraries that are included via the \fB\-l\fR command line |
| 2342 |
option. Searches for \fB\-l\fR libraries are only conducted in |
| 2343 |
directories specified by the \fB\-L\fR option. |
| 2344 |
.RS 4 |
| 2345 |
.IP 1. 4 |
| 2346 |
Any directories specified by \fB\-rpath\-link\fR options. |
| 2347 |
.IP 2. 4 |
| 2348 |
Any directories specified by \fB\-rpath\fR options. The difference |
| 2349 |
between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories |
| 2350 |
specified by \fB\-rpath\fR options are included in the executable and |
| 2351 |
used at runtime, whereas the \fB\-rpath\-link\fR option is only effective |
| 2352 |
at link time. Searching \fB\-rpath\fR in this way is only supported |
| 2353 |
by native linkers and cross linkers which have been configured with |
| 2354 |
the \fB\-\-with\-sysroot\fR option. |
| 2355 |
.IP 3. 4 |
| 2356 |
On an ELF system, for native linkers, if the \fB\-rpath\fR and |
| 2357 |
\&\fB\-rpath\-link\fR options were not used, search the contents of the |
| 2358 |
environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR. |
| 2359 |
.IP 4. 4 |
| 2360 |
On SunOS, if the \fB\-rpath\fR option was not used, search any |
| 2361 |
directories specified using \fB\-L\fR options. |
| 2362 |
.IP 5. 4 |
| 2363 |
For a native linker, search the contents of the environment |
| 2364 |
variable \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR. |
| 2365 |
.IP 6. 4 |
| 2366 |
For a native ELF linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or |
| 2367 |
\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared |
| 2368 |
libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if |
| 2369 |
\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist. |
| 2370 |
.IP 7. 4 |
| 2371 |
For a linker for a Linux system, if the file \fI/etc/ld.so.conf\fR |
| 2372 |
exists, the list of directories found in that file. Note: the path |
| 2373 |
to this file is prefixed with the \f(CW\*(C`sysroot\*(C'\fR value, if that is |
| 2374 |
defined, and then any \f(CW\*(C`prefix\*(C'\fR string if the linker was |
| 2375 |
configured with the \fB\-\-prefix=<path>\fR option. |
| 2376 |
.IP 8. 4 |
| 2377 |
For a native linker on a FreeBSD system, any directories specified by |
| 2378 |
the \f(CW\*(C`_PATH_ELF_HINTS\*(C'\fR macro defined in the \fIelf\-hints.h\fR |
| 2379 |
header file. |
| 2380 |
.IP 9. 4 |
| 2381 |
Any directories specified by a \f(CW\*(C`SEARCH_DIR\*(C'\fR command in a |
| 2382 |
linker script given on the command line, including scripts specified |
| 2383 |
by \fB\-T\fR (but not \fB\-dT\fR). |
| 2384 |
.IP 10. 4 |
| 2385 |
The default directories, normally \fI/lib\fR and \fI/usr/lib\fR. |
| 2386 |
.IP 11. 4 |
| 2387 |
Any directories specified by a plugin LDPT_SET_EXTRA_LIBRARY_PATH. |
| 2388 |
.IP 12. 4 |
| 2389 |
Any directories specified by a \f(CW\*(C`SEARCH_DIR\*(C'\fR command in a default |
| 2390 |
linker script. |
| 2391 |
.RE |
| 2392 |
.RS 4 |
| 2393 |
.Sp |
| 2394 |
Note however on Linux based systems there is an additional caveat: If |
| 2395 |
the \fB\-\-as\-needed\fR option is active \fIand\fR a shared library |
| 2396 |
is located which would normally satisfy the search \fIand\fR this |
| 2397 |
library does not have DT_NEEDED tag for \fIlibc.so\fR |
| 2398 |
\&\fIand\fR there is a shared library later on in the set of search |
| 2399 |
directories which also satisfies the search \fIand\fR |
| 2400 |
this second shared library does have a DT_NEEDED tag for |
| 2401 |
\&\fIlibc.so\fR \fIthen\fR the second library will be selected instead |
| 2402 |
of the first. |
| 2403 |
.Sp |
| 2404 |
If the required shared library is not found, the linker will issue a |
| 2405 |
warning and continue with the link. |
| 2406 |
.RE |
| 2407 |
.IP \fB\-\-section\-ordering\-file=\fR\fIscript\fR 4 |
| 2408 |
.IX Item "--section-ordering-file=script" |
| 2409 |
This option is used to augment the current linker script with |
| 2410 |
additional mapping of input sections to output sections. This file |
| 2411 |
must use the same syntax for \f(CW\*(C`SECTIONS\*(C'\fR as is used in normal |
| 2412 |
linker scripts, but it should not do anything other than place input |
| 2413 |
sections into output sections. \f(CW@pxref\fR{SECTIONS} |
| 2414 |
.Sp |
| 2415 |
A second constraint on the section ordering script is that it can only |
| 2416 |
reference output sections that are already defined by whichever linker |
| 2417 |
script is currently in use. (Ie the default linker script or a script |
| 2418 |
specified on the command line). The benefit of the section ordering |
| 2419 |
script however is that the input sections are mapped to the start of |
| 2420 |
the output sections, so that they can ensure the ordering of sections |
| 2421 |
in the output section. For example, imagine that the default linker |
| 2422 |
script looks like this: |
| 2423 |
.Sp |
| 2424 |
.Vb 4 |
| 2425 |
\& SECTIONS { |
| 2426 |
\& .text : { *(.text.hot) ; *(.text .text.*) } |
| 2427 |
\& .data : { *(.data.big) ; *(.data .data.*) } |
| 2428 |
\& } |
| 2429 |
.Ve |
| 2430 |
.Sp |
| 2431 |
Then if a section ordering file like this is used: |
| 2432 |
.Sp |
| 2433 |
.Vb 2 |
| 2434 |
\& .text : { *(.text.first) ; *(.text.z*) } |
| 2435 |
\& .data : { foo.o(.data.first) ; *(.data.small) } |
| 2436 |
.Ve |
| 2437 |
.Sp |
| 2438 |
This would be equivalent to a linker script like this: |
| 2439 |
.Sp |
| 2440 |
.Vb 4 |
| 2441 |
\& SECTIONS { |
| 2442 |
\& .text : { *(.text.first) ; *(.text.z*) ; *(.text.hot) ; *(.text .text.*) } |
| 2443 |
\& .data : { foo.o(.data.first) ; *(.data.small) ; *(.data.big) ; *(.data .data.*) } |
| 2444 |
\& } |
| 2445 |
.Ve |
| 2446 |
.Sp |
| 2447 |
The advantage of the section ordering file is that it can be used to |
| 2448 |
order those sections that matter to the user without having to worry |
| 2449 |
about any other sections, or memory regions, or anything else. |
| 2450 |
.IP \fB\-shared\fR 4 |
| 2451 |
.IX Item "-shared" |
| 2452 |
.PD 0 |
| 2453 |
.IP \fB\-Bshareable\fR 4 |
| 2454 |
.IX Item "-Bshareable" |
| 2455 |
.PD |
| 2456 |
Create a shared library. This is currently only supported on ELF, XCOFF |
| 2457 |
and SunOS platforms. On SunOS, the linker will automatically create a |
| 2458 |
shared library if the \fB\-e\fR option is not used and there are |
| 2459 |
undefined symbols in the link. |
| 2460 |
.IP \fB\-\-sort\-common\fR 4 |
| 2461 |
.IX Item "--sort-common" |
| 2462 |
.PD 0 |
| 2463 |
.IP \fB\-\-sort\-common=ascending\fR 4 |
| 2464 |
.IX Item "--sort-common=ascending" |
| 2465 |
.IP \fB\-\-sort\-common=descending\fR 4 |
| 2466 |
.IX Item "--sort-common=descending" |
| 2467 |
.PD |
| 2468 |
This option tells \fBld\fR to sort the common symbols by alignment in |
| 2469 |
ascending or descending order when it places them in the appropriate output |
| 2470 |
sections. The symbol alignments considered are sixteen-byte or larger, |
| 2471 |
eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps |
| 2472 |
between symbols due to alignment constraints. If no sorting order is |
| 2473 |
specified, then descending order is assumed. |
| 2474 |
.IP \fB\-\-sort\-section=name\fR 4 |
| 2475 |
.IX Item "--sort-section=name" |
| 2476 |
This option will apply \f(CW\*(C`SORT_BY_NAME\*(C'\fR to all wildcard section |
| 2477 |
patterns in the linker script. |
| 2478 |
.IP \fB\-\-sort\-section=alignment\fR 4 |
| 2479 |
.IX Item "--sort-section=alignment" |
| 2480 |
This option will apply \f(CW\*(C`SORT_BY_ALIGNMENT\*(C'\fR to all wildcard section |
| 2481 |
patterns in the linker script. |
| 2482 |
.IP \fB\-\-spare\-dynamic\-tags=\fR\fIcount\fR 4 |
| 2483 |
.IX Item "--spare-dynamic-tags=count" |
| 2484 |
This option specifies the number of empty slots to leave in the |
| 2485 |
\&.dynamic section of ELF shared objects. Empty slots may be needed by |
| 2486 |
post processing tools, such as the prelinker. The default is 5. |
| 2487 |
.IP \fB\-\-split\-by\-file[=\fR\fIsize\fR\fB]\fR 4 |
| 2488 |
.IX Item "--split-by-file[=size]" |
| 2489 |
Similar to \fB\-\-split\-by\-reloc\fR but creates a new output section for |
| 2490 |
each input file when \fIsize\fR is reached. \fIsize\fR defaults to a |
| 2491 |
size of 1 if not given. |
| 2492 |
.IP \fB\-\-split\-by\-reloc[=\fR\fIcount\fR\fB]\fR 4 |
| 2493 |
.IX Item "--split-by-reloc[=count]" |
| 2494 |
Tries to creates extra sections in the output file so that no single |
| 2495 |
output section in the file contains more than \fIcount\fR relocations. |
| 2496 |
This is useful when generating huge relocatable files for downloading into |
| 2497 |
certain real time kernels with the COFF object file format; since COFF |
| 2498 |
cannot represent more than 65535 relocations in a single section. Note |
| 2499 |
that this will fail to work with object file formats which do not |
| 2500 |
support arbitrary sections. The linker will not split up individual |
| 2501 |
input sections for redistribution, so if a single input section contains |
| 2502 |
more than \fIcount\fR relocations one output section will contain that |
| 2503 |
many relocations. \fIcount\fR defaults to a value of 32768. |
| 2504 |
.IP \fB\-\-stats[=\fR\fIfilename\fR\fB]\fR 4 |
| 2505 |
.IX Item "--stats[=filename]" |
| 2506 |
Compute and display statistics about the operation of the linker, such |
| 2507 |
as execution time and memory usage. |
| 2508 |
.Sp |
| 2509 |
If the optional \fIfilename\fR argument is not supplied then only |
| 2510 |
basic information is reported, and it is sent to the standard error |
| 2511 |
output stream. If the \fIfilename\fR argument is supplied then |
| 2512 |
extended information is written to the named file. If \fIfilename\fR |
| 2513 |
is set to just the \fI\-\fR symbol, then the extended information is |
| 2514 |
sent to the standard output stream. If the \fIfilename\fR starts with |
| 2515 |
\&\fI+\fR then the file is opened in append mode rather than overwrite |
| 2516 |
mode. |
| 2517 |
.Sp |
| 2518 |
If the \fB\-Map\fR option has been enabled then the information is |
| 2519 |
also recorded in the map file as well. Note: if both the |
| 2520 |
\&\fB\-\-stats\fR option and the \fB\-Map\fR options have been given |
| 2521 |
\&\fIfilename\fR arguments and they match, then the information will |
| 2522 |
only be written out once not twice. |
| 2523 |
.Sp |
| 2524 |
If the \f(CW\*(C`LD_STATS\*(C'\fR environment variable is defined then this |
| 2525 |
behaves likes the \fB\-\-stats\fR option. If the variable's value is |
| 2526 |
a string then this will used as the name of a file into which the |
| 2527 |
information should be recorded. Otherwise the information |
| 2528 |
will be sent to the standard output stream. Using the environment |
| 2529 |
variable allows stats to be recorded without having to alter the |
| 2530 |
linker's command line. Note: if both the environment variable and the |
| 2531 |
\&\fB\-\-stats\fR option are used then the \fB\-\-stats\fR option |
| 2532 |
takes precedence. |
| 2533 |
.Sp |
| 2534 |
The extended information reported includes the cpu time used and, if |
| 2535 |
the \fR\f(BIgetrusage()\fR\fI\fR system library call is available then maximum |
| 2536 |
set size and the user and system run times as well. In addition if |
| 2537 |
the \fImallinfo\fR or \fImallinfo2\fR system library calls are |
| 2538 |
available then the total memory usage is reported, |
| 2539 |
.Sp |
| 2540 |
The information is displayed for individual parts of the linking |
| 2541 |
process which are referred to as \fIphases\fR. Note that |
| 2542 |
individual phases can contain or overlap with each other so it should |
| 2543 |
not be assumed that the overall resources used by the linker is the |
| 2544 |
sum of the resources used by the individual phases. |
| 2545 |
.Sp |
| 2546 |
In addition the information is also reported for a special phase |
| 2547 |
called \fIALL\fR which covers the entire linking process. |
| 2548 |
.Sp |
| 2549 |
When extended information is being reported the linker version, |
| 2550 |
command line arguments and linker start time are also included. This |
| 2551 |
makes it easier to handle the situation where multiple links are being |
| 2552 |
invoked by a build system and to indentify exactly which arguments |
| 2553 |
were responsible for producing the statistics that are reported. |
| 2554 |
.Sp |
| 2555 |
The extended output looks something like this: |
| 2556 |
.Sp |
| 2557 |
.Vb 3 |
| 2558 |
\& Stats: linker version: (GNU Binutils) 2.44.50.20250401 |
| 2559 |
\& Stats: linker started: Wed Apr 2 09:36:41 2025 |
| 2560 |
\& Stats: args: ld \-z norelro \-z nomemory\-seal \-z no\-separate\-code \-o a.out [...] |
| 2561 |
\& |
| 2562 |
\& Stats: phase cpu time rss user time system time memory |
| 2563 |
\& Stats: name (microsec) (KiB) (seconds) (seconds) (KiB) |
| 2564 |
\& Stats: ALL 390082 217740 0 0 25219440 |
| 2565 |
\& Stats: ctf processing 12 0 0 0 0 |
| 2566 |
\& Stats: string merge 1324 0 0 0 406544 |
| 2567 |
\& Stats: parsing 349 288 0 0 119792 |
| 2568 |
\& Stats: plugins 1 0 0 0 0 |
| 2569 |
\& Stats: processing files 259616 214524 0 0 31569120 |
| 2570 |
\& Stats: write 116493 0 0 0 48096 |
| 2571 |
.Ve |
| 2572 |
.IP \fB\-\-no\-stats\fR 4 |
| 2573 |
.IX Item "--no-stats" |
| 2574 |
Disables the reporting of usage statistics, should it have been |
| 2575 |
enabled via the \fB\-\-stats\fR command line option or the |
| 2576 |
\&\fILD_STATS\fR environment variable. |
| 2577 |
.IP \fB\-\-sysroot=\fR\fIdirectory\fR 4 |
| 2578 |
.IX Item "--sysroot=directory" |
| 2579 |
Use \fIdirectory\fR as the location of the sysroot, overriding the |
| 2580 |
configure-time default. This option is only supported by linkers |
| 2581 |
that were configured using \fB\-\-with\-sysroot\fR. |
| 2582 |
.IP \fB\-\-task\-link\fR 4 |
| 2583 |
.IX Item "--task-link" |
| 2584 |
This is used by COFF/PE based targets to create a task-linked object |
| 2585 |
file where all of the global symbols have been converted to statics. |
| 2586 |
.IP \fB\-\-traditional\-format\fR 4 |
| 2587 |
.IX Item "--traditional-format" |
| 2588 |
For some targets, the output of \fBld\fR is different in some ways from |
| 2589 |
the output of some existing linker. This switch requests \fBld\fR to |
| 2590 |
use the traditional format instead. |
| 2591 |
.Sp |
| 2592 |
For example, on SunOS, \fBld\fR combines duplicate entries in the |
| 2593 |
symbol string table. This can reduce the size of an output file with |
| 2594 |
full debugging information by over 30 percent. Unfortunately, the SunOS |
| 2595 |
\&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no |
| 2596 |
trouble). The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not |
| 2597 |
combine duplicate entries. |
| 2598 |
.IP \fB\-\-section\-start=\fR\fIsectionname\fR\fB=\fR\fIorg\fR 4 |
| 2599 |
.IX Item "--section-start=sectionname=org" |
| 2600 |
Locate a section in the output file at the absolute |
| 2601 |
address given by \fIorg\fR. You may use this option as many |
| 2602 |
times as necessary to locate multiple sections in the command |
| 2603 |
line. |
| 2604 |
\&\fIorg\fR must be a single hexadecimal integer; |
| 2605 |
for compatibility with other linkers, you may omit the leading |
| 2606 |
\&\fB0x\fR usually associated with hexadecimal values. \fINote:\fR there |
| 2607 |
should be no white space between \fIsectionname\fR, the equals |
| 2608 |
sign ("\fB=\fR"), and \fIorg\fR. |
| 2609 |
.IP \fB\-\-image\-base=\fR\fIorg\fR 4 |
| 2610 |
.IX Item "--image-base=org" |
| 2611 |
When using ELF, same as \fB\-Ttext\-segment\fR, with both options effectively |
| 2612 |
setting the base address of the ELF executable. |
| 2613 |
.Sp |
| 2614 |
When using PE, use \fIvalue\fR as the base address of your program or dll. |
| 2615 |
This is the lowest memory location that will be used when your program or |
| 2616 |
dll is loaded. To reduce the need to relocate and improve performance of |
| 2617 |
your dlls, each should have a unique base address and not overlap any |
| 2618 |
other dlls. The default is 0x400000 for executables, and 0x10000000 |
| 2619 |
for dlls. |
| 2620 |
.IP \fB\-Tbss=\fR\fIorg\fR 4 |
| 2621 |
.IX Item "-Tbss=org" |
| 2622 |
.PD 0 |
| 2623 |
.IP \fB\-Tdata=\fR\fIorg\fR 4 |
| 2624 |
.IX Item "-Tdata=org" |
| 2625 |
.IP \fB\-Ttext=\fR\fIorg\fR 4 |
| 2626 |
.IX Item "-Ttext=org" |
| 2627 |
.PD |
| 2628 |
Same as \fB\-\-section\-start\fR, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or |
| 2629 |
\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR. |
| 2630 |
.IP \fB\-Ttext\-segment=\fR\fIorg\fR 4 |
| 2631 |
.IX Item "-Ttext-segment=org" |
| 2632 |
When creating an ELF executable, it will set the address of the first |
| 2633 |
byte of the first segment. Note that when \fB\-pie\fR is used with |
| 2634 |
\&\fB\-Ttext\-segment=\fR\fIorg\fR, the output executable is marked |
| 2635 |
ET_EXEC so that the address of the first byte of the text segment will |
| 2636 |
be guaranteed to be \fIorg\fR at run time. |
| 2637 |
.IP \fB\-Trodata\-segment=\fR\fIorg\fR 4 |
| 2638 |
.IX Item "-Trodata-segment=org" |
| 2639 |
When creating an ELF executable or shared object for a target where |
| 2640 |
the read-only data is in its own segment separate from the executable |
| 2641 |
text, it will set the address of the first byte of the read-only data segment. |
| 2642 |
.IP \fB\-Tldata\-segment=\fR\fIorg\fR 4 |
| 2643 |
.IX Item "-Tldata-segment=org" |
| 2644 |
When creating an ELF executable or shared object for x86\-64 medium memory |
| 2645 |
model, it will set the address of the first byte of the ldata segment. |
| 2646 |
.IP \fB\-\-unresolved\-symbols=\fR\fImethod\fR 4 |
| 2647 |
.IX Item "--unresolved-symbols=method" |
| 2648 |
Determine how to handle unresolved symbols. There are four possible |
| 2649 |
values for \fBmethod\fR: |
| 2650 |
.RS 4 |
| 2651 |
.IP \fBignore-all\fR 4 |
| 2652 |
.IX Item "ignore-all" |
| 2653 |
Do not report any unresolved symbols. |
| 2654 |
.IP \fBreport-all\fR 4 |
| 2655 |
.IX Item "report-all" |
| 2656 |
Report all unresolved symbols. This is the default. |
| 2657 |
.IP \fBignore-in-object-files\fR 4 |
| 2658 |
.IX Item "ignore-in-object-files" |
| 2659 |
Report unresolved symbols that are contained in shared libraries, but |
| 2660 |
ignore them if they come from regular object files. |
| 2661 |
.IP \fBignore-in-shared-libs\fR 4 |
| 2662 |
.IX Item "ignore-in-shared-libs" |
| 2663 |
Report unresolved symbols that come from regular object files, but |
| 2664 |
ignore them if they come from shared libraries. This can be useful |
| 2665 |
when creating a dynamic binary and it is known that all the shared |
| 2666 |
libraries that it should be referencing are included on the linker's |
| 2667 |
command line. |
| 2668 |
.RE |
| 2669 |
.RS 4 |
| 2670 |
.Sp |
| 2671 |
The behaviour for shared libraries on their own can also be controlled |
| 2672 |
by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option. |
| 2673 |
.Sp |
| 2674 |
Normally the linker will generate an error message for each reported |
| 2675 |
unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR |
| 2676 |
can change this to a warning. |
| 2677 |
.RE |
| 2678 |
.IP \fB\-\-dll\-verbose\fR 4 |
| 2679 |
.IX Item "--dll-verbose" |
| 2680 |
.PD 0 |
| 2681 |
.IP \fB\-\-verbose[=\fR\fINUMBER\fR\fB]\fR 4 |
| 2682 |
.IX Item "--verbose[=NUMBER]" |
| 2683 |
.PD |
| 2684 |
Display the version number for \fBld\fR and list the linker emulations |
| 2685 |
supported. Display which input files can and cannot be opened. Display |
| 2686 |
the linker script being used by the linker. If the optional \fINUMBER\fR |
| 2687 |
argument > 1, plugin symbol status will also be displayed. |
| 2688 |
.IP \fB\-\-version\-script=\fR\fIversion-scriptfile\fR 4 |
| 2689 |
.IX Item "--version-script=version-scriptfile" |
| 2690 |
Specify the name of a version script to the linker. This is typically |
| 2691 |
used when creating shared libraries to specify additional information |
| 2692 |
about the version hierarchy for the library being created. This option |
| 2693 |
is only fully supported on ELF platforms which support shared libraries; |
| 2694 |
see \fBVERSION\fR. It is partially supported on PE platforms, which can |
| 2695 |
use version scripts to filter symbol visibility in auto-export mode: any |
| 2696 |
symbols marked \fBlocal\fR in the version script will not be exported. |
| 2697 |
.IP \fB\-\-warn\-common\fR 4 |
| 2698 |
.IX Item "--warn-common" |
| 2699 |
Warn when a common symbol is combined with another common symbol or with |
| 2700 |
a symbol definition. Unix linkers allow this somewhat sloppy practice, |
| 2701 |
but linkers on some other operating systems do not. This option allows |
| 2702 |
you to find potential problems from combining global symbols. |
| 2703 |
Unfortunately, some C libraries use this practice, so you may get some |
| 2704 |
warnings about symbols in the libraries as well as in your programs. |
| 2705 |
.Sp |
| 2706 |
There are three kinds of global symbols, illustrated here by C examples: |
| 2707 |
.RS 4 |
| 2708 |
.IP "\fBint i = 1;\fR" 4 |
| 2709 |
.IX Item "int i = 1;" |
| 2710 |
A definition, which goes in the initialized data section of the output |
| 2711 |
file. |
| 2712 |
.IP "\fBextern int i;\fR" 4 |
| 2713 |
.IX Item "extern int i;" |
| 2714 |
An undefined reference, which does not allocate space. |
| 2715 |
There must be either a definition or a common symbol for the |
| 2716 |
variable somewhere. |
| 2717 |
.IP "\fBint i;\fR" 4 |
| 2718 |
.IX Item "int i;" |
| 2719 |
A common symbol. If there are only (one or more) common symbols for a |
| 2720 |
variable, it goes in the uninitialized data area of the output file. |
| 2721 |
The linker merges multiple common symbols for the same variable into a |
| 2722 |
single symbol. If they are of different sizes, it picks the largest |
| 2723 |
size. The linker turns a common symbol into a declaration, if there is |
| 2724 |
a definition of the same variable. |
| 2725 |
.RE |
| 2726 |
.RS 4 |
| 2727 |
.Sp |
| 2728 |
The \fB\-\-warn\-common\fR option can produce five kinds of warnings. |
| 2729 |
Each warning consists of a pair of lines: the first describes the symbol |
| 2730 |
just encountered, and the second describes the previous symbol |
| 2731 |
encountered with the same name. One or both of the two symbols will be |
| 2732 |
a common symbol. |
| 2733 |
.IP 1. 4 |
| 2734 |
Turning a common symbol into a reference, because there is already a |
| 2735 |
definition for the symbol. |
| 2736 |
.Sp |
| 2737 |
.Vb 3 |
| 2738 |
\& <file>(<section>): warning: common of \`<symbol>\*(Aq |
| 2739 |
\& overridden by definition |
| 2740 |
\& <file>(<section>): warning: defined here |
| 2741 |
.Ve |
| 2742 |
.IP 2. 4 |
| 2743 |
Turning a common symbol into a reference, because a later definition for |
| 2744 |
the symbol is encountered. This is the same as the previous case, |
| 2745 |
except that the symbols are encountered in a different order. |
| 2746 |
.Sp |
| 2747 |
.Vb 3 |
| 2748 |
\& <file>(<section>): warning: definition of \`<symbol>\*(Aq |
| 2749 |
\& overriding common |
| 2750 |
\& <file>(<section>): warning: common is here |
| 2751 |
.Ve |
| 2752 |
.IP 3. 4 |
| 2753 |
Merging a common symbol with a previous same-sized common symbol. |
| 2754 |
.Sp |
| 2755 |
.Vb 3 |
| 2756 |
\& <file>(<section>): warning: multiple common |
| 2757 |
\& of \`<symbol>\*(Aq |
| 2758 |
\& <file>(<section>): warning: previous common is here |
| 2759 |
.Ve |
| 2760 |
.IP 4. 4 |
| 2761 |
Merging a common symbol with a previous larger common symbol. |
| 2762 |
.Sp |
| 2763 |
.Vb 3 |
| 2764 |
\& <file>(<section>): warning: common of \`<symbol>\*(Aq |
| 2765 |
\& overridden by larger common |
| 2766 |
\& <file>(<section>): warning: larger common is here |
| 2767 |
.Ve |
| 2768 |
.IP 5. 4 |
| 2769 |
Merging a common symbol with a previous smaller common symbol. This is |
| 2770 |
the same as the previous case, except that the symbols are |
| 2771 |
encountered in a different order. |
| 2772 |
.Sp |
| 2773 |
.Vb 3 |
| 2774 |
\& <file>(<section>): warning: common of \`<symbol>\*(Aq |
| 2775 |
\& overriding smaller common |
| 2776 |
\& <file>(<section>): warning: smaller common is here |
| 2777 |
.Ve |
| 2778 |
.RE |
| 2779 |
.RS 4 |
| 2780 |
.RE |
| 2781 |
.IP \fB\-\-warn\-constructors\fR 4 |
| 2782 |
.IX Item "--warn-constructors" |
| 2783 |
Warn if any global constructors are used. This is only useful for a few |
| 2784 |
object file formats. For formats like COFF or ELF, the linker can not |
| 2785 |
detect the use of global constructors. |
| 2786 |
.IP \fB\-\-warn\-execstack\fR 4 |
| 2787 |
.IX Item "--warn-execstack" |
| 2788 |
.PD 0 |
| 2789 |
.IP \fB\-\-warn\-execstack\-objects\fR 4 |
| 2790 |
.IX Item "--warn-execstack-objects" |
| 2791 |
.IP \fB\-\-no\-warn\-execstack\fR 4 |
| 2792 |
.IX Item "--no-warn-execstack" |
| 2793 |
.PD |
| 2794 |
On ELF platforms the linker may generate warning messages if it is |
| 2795 |
asked to create an output file that contains an executable stack. |
| 2796 |
There are three possible states: |
| 2797 |
.RS 4 |
| 2798 |
.IP 1. 4 |
| 2799 |
Do not generate any warnings. |
| 2800 |
.IP 2. 4 |
| 2801 |
Always generate warnings, even if the executable stack is requested |
| 2802 |
via the \fB\-z execstack\fR command line option. |
| 2803 |
.IP 3. 4 |
| 2804 |
Only generate a warning if an object file requests an executable |
| 2805 |
stack, but not if the \fB\-z execstack\fR option is used. |
| 2806 |
.RE |
| 2807 |
.RS 4 |
| 2808 |
.Sp |
| 2809 |
The default state depends upon how the linker was configured when it |
| 2810 |
was built. The \fB\-\-no\-warn\-execstack\fR option always puts the |
| 2811 |
linker into the no-warnings state. The \fB\-\-warn\-execstack\fR |
| 2812 |
option puts the linker into the warn-always state. The |
| 2813 |
\&\fB\-\-warn\-execstack\-objects\fR option puts the linker into the |
| 2814 |
warn-for-object-files-only state. |
| 2815 |
.Sp |
| 2816 |
Note: ELF format input files can specify that they need an executable |
| 2817 |
stack by having a \fI.note.GNU\-stack\fR section with the executable |
| 2818 |
bit set in its section flags. They can specify that they do not need |
| 2819 |
an executable stack by having the same section, but without the |
| 2820 |
executable flag bit set. If an input file does not have a |
| 2821 |
\&\fI.note.GNU\-stack\fR section then the default behaviour is target |
| 2822 |
specific. For some targets, then absence of such a section implies |
| 2823 |
that an executable stack \fIis\fR required. This is often a problem |
| 2824 |
for hand crafted assembler files. |
| 2825 |
.RE |
| 2826 |
.IP \fB\-\-error\-execstack\fR 4 |
| 2827 |
.IX Item "--error-execstack" |
| 2828 |
.PD 0 |
| 2829 |
.IP \fB\-\-no\-error\-execstack\fR 4 |
| 2830 |
.IX Item "--no-error-execstack" |
| 2831 |
.PD |
| 2832 |
If the linker is going to generate a warning message about an |
| 2833 |
executable stack then the \fB\-\-error\-execstack\fR option will |
| 2834 |
instead change that warning into an error. Note \- this option does |
| 2835 |
not change the linker's execstack warning generation state. Use |
| 2836 |
\&\fB\-\-warn\-execstack\fR or \fB\-\-warn\-execstack\-objects\fR to set |
| 2837 |
a specific warning state. |
| 2838 |
.Sp |
| 2839 |
The \fB\-\-no\-error\-execstack\fR option will restore the default |
| 2840 |
behaviour of generating warning messages. |
| 2841 |
.IP \fB\-\-warn\-multiple\-gp\fR 4 |
| 2842 |
.IX Item "--warn-multiple-gp" |
| 2843 |
Warn if multiple global pointer values are required in the output file. |
| 2844 |
This is only meaningful for certain processors, such as the Alpha. |
| 2845 |
Specifically, some processors put large-valued constants in a special |
| 2846 |
section. A special register (the global pointer) points into the middle |
| 2847 |
of this section, so that constants can be loaded efficiently via a |
| 2848 |
base-register relative addressing mode. Since the offset in |
| 2849 |
base-register relative mode is fixed and relatively small (e.g., 16 |
| 2850 |
bits), this limits the maximum size of the constant pool. Thus, in |
| 2851 |
large programs, it is often necessary to use multiple global pointer |
| 2852 |
values in order to be able to address all possible constants. This |
| 2853 |
option causes a warning to be issued whenever this case occurs. |
| 2854 |
.IP \fB\-\-warn\-once\fR 4 |
| 2855 |
.IX Item "--warn-once" |
| 2856 |
Only warn once for each undefined symbol, rather than once per module |
| 2857 |
which refers to it. |
| 2858 |
.IP \fB\-\-warn\-rwx\-segments\fR 4 |
| 2859 |
.IX Item "--warn-rwx-segments" |
| 2860 |
.PD 0 |
| 2861 |
.IP \fB\-\-no\-warn\-rwx\-segments\fR 4 |
| 2862 |
.IX Item "--no-warn-rwx-segments" |
| 2863 |
.PD |
| 2864 |
Warn if the linker creates a loadable, non-zero sized segment that has |
| 2865 |
all three of the read, write and execute permission flags set. Such a |
| 2866 |
segment represents a potential security vulnerability. In addition |
| 2867 |
warnings will be generated if a thread local storage segment is |
| 2868 |
created with the execute permission flag set, regardless of whether or |
| 2869 |
not it has the read and/or write flags set. |
| 2870 |
.Sp |
| 2871 |
These warnings are enabled by default. They can be disabled via the |
| 2872 |
\&\fB\-\-no\-warn\-rwx\-segments\fR option and re-enabled via the |
| 2873 |
\&\fB\-\-warn\-rwx\-segments\fR option. |
| 2874 |
.IP \fB\-\-error\-rwx\-segments\fR 4 |
| 2875 |
.IX Item "--error-rwx-segments" |
| 2876 |
.PD 0 |
| 2877 |
.IP \fB\-\-no\-error\-rwx\-segments\fR 4 |
| 2878 |
.IX Item "--no-error-rwx-segments" |
| 2879 |
.PD |
| 2880 |
If the linker is going to generate a warning message about an |
| 2881 |
executable, writeable segment, or an executable TLS segment, then the |
| 2882 |
\&\fB\-\-error\-rwx\-segments\fR option will turn this warning into an |
| 2883 |
error instead. The \fB\-\-no\-error\-rwx\-segments\fR option will |
| 2884 |
restore the default behaviour of just generating a warning message. |
| 2885 |
.Sp |
| 2886 |
Note \- the \fB\-\-error\-rwx\-segments\fR option does not by itself |
| 2887 |
turn on warnings about these segments. These warnings are either |
| 2888 |
enabled by default, if the linker was configured that way, or via the |
| 2889 |
\&\fB\-\-warn\-rwx\-segments\fR command line option. |
| 2890 |
.IP \fB\-\-warn\-section\-align\fR 4 |
| 2891 |
.IX Item "--warn-section-align" |
| 2892 |
Warn if the address of an output section is changed because of |
| 2893 |
alignment. Typically, the alignment will be set by an input section. |
| 2894 |
The address will only be changed if it not explicitly specified; that |
| 2895 |
is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for |
| 2896 |
the section. |
| 2897 |
.IP \fB\-\-warn\-textrel\fR 4 |
| 2898 |
.IX Item "--warn-textrel" |
| 2899 |
Warn if the linker adds DT_TEXTREL to a position-independent executable |
| 2900 |
or shared object. |
| 2901 |
.IP \fB\-\-warn\-alternate\-em\fR 4 |
| 2902 |
.IX Item "--warn-alternate-em" |
| 2903 |
Warn if an object has alternate ELF machine code. |
| 2904 |
.IP \fB\-\-warn\-unresolved\-symbols\fR 4 |
| 2905 |
.IX Item "--warn-unresolved-symbols" |
| 2906 |
If the linker is going to report an unresolved symbol (see the option |
| 2907 |
\&\fB\-\-unresolved\-symbols\fR) it will normally generate an error. |
| 2908 |
This option makes it generate a warning instead. |
| 2909 |
.IP \fB\-\-error\-unresolved\-symbols\fR 4 |
| 2910 |
.IX Item "--error-unresolved-symbols" |
| 2911 |
This restores the linker's default behaviour of generating errors when |
| 2912 |
it is reporting unresolved symbols. |
| 2913 |
.IP \fB\-\-whole\-archive\fR 4 |
| 2914 |
.IX Item "--whole-archive" |
| 2915 |
For each archive mentioned on the command line after the |
| 2916 |
\&\fB\-\-whole\-archive\fR option, include every object file in the archive |
| 2917 |
in the link, rather than searching the archive for the required object |
| 2918 |
files. This is normally used to turn an archive file into a shared |
| 2919 |
library, forcing every object to be included in the resulting shared |
| 2920 |
library. This option may be used more than once. |
| 2921 |
.Sp |
| 2922 |
Two notes when using this option from gcc: First, gcc doesn't know |
| 2923 |
about this option, so you have to use \fB\-Wl,\-whole\-archive\fR. |
| 2924 |
Second, don't forget to use \fB\-Wl,\-no\-whole\-archive\fR after your |
| 2925 |
list of archives, because gcc will add its own list of archives to |
| 2926 |
your link and you may not want this flag to affect those as well. |
| 2927 |
.IP \fB\-\-wrap=\fR\fIsymbol\fR 4 |
| 2928 |
.IX Item "--wrap=symbol" |
| 2929 |
Use a wrapper function for \fIsymbol\fR. Any undefined reference to |
| 2930 |
\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. Any |
| 2931 |
undefined reference to \f(CW\*(C`_\|_real_\fR\f(CIsymbol\fR\f(CW\*(C'\fR will be resolved to |
| 2932 |
\&\fIsymbol\fR. |
| 2933 |
.Sp |
| 2934 |
This can be used to provide a wrapper for a system function. The |
| 2935 |
wrapper function should be called \f(CW\*(C`_\|_wrap_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. If it |
| 2936 |
wishes to call the system function, it should call |
| 2937 |
\&\f(CW\*(C`_\|_real_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. |
| 2938 |
.Sp |
| 2939 |
Here is a trivial example: |
| 2940 |
.Sp |
| 2941 |
.Vb 6 |
| 2942 |
\& void * |
| 2943 |
\& _\|_wrap_malloc (size_t c) |
| 2944 |
\& { |
| 2945 |
\& printf ("malloc called with %zu\en", c); |
| 2946 |
\& return _\|_real_malloc (c); |
| 2947 |
\& } |
| 2948 |
.Ve |
| 2949 |
.Sp |
| 2950 |
If you link other code with this file using \fB\-\-wrap malloc\fR, then |
| 2951 |
all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR |
| 2952 |
instead. The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will |
| 2953 |
call the real \f(CW\*(C`malloc\*(C'\fR function. |
| 2954 |
.Sp |
| 2955 |
You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that |
| 2956 |
links without the \fB\-\-wrap\fR option will succeed. If you do this, |
| 2957 |
you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same |
| 2958 |
file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the |
| 2959 |
call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR. |
| 2960 |
.Sp |
| 2961 |
Only undefined references are replaced by the linker. So, translation unit |
| 2962 |
internal references to \fIsymbol\fR are not resolved to |
| 2963 |
\&\f(CW\*(C`_\|_wrap_\fR\f(CIsymbol\fR\f(CW\*(C'\fR. In the next example, the call to \f(CW\*(C`f\*(C'\fR in |
| 2964 |
\&\f(CW\*(C`g\*(C'\fR is not resolved to \f(CW\*(C`_\|_wrap_f\*(C'\fR. |
| 2965 |
.Sp |
| 2966 |
.Vb 5 |
| 2967 |
\& int |
| 2968 |
\& f (void) |
| 2969 |
\& { |
| 2970 |
\& return 123; |
| 2971 |
\& } |
| 2972 |
\& |
| 2973 |
\& int |
| 2974 |
\& g (void) |
| 2975 |
\& { |
| 2976 |
\& return f(); |
| 2977 |
\& } |
| 2978 |
.Ve |
| 2979 |
.IP \fB\-\-eh\-frame\-hdr\fR 4 |
| 2980 |
.IX Item "--eh-frame-hdr" |
| 2981 |
.PD 0 |
| 2982 |
.IP \fB\-\-no\-eh\-frame\-hdr\fR 4 |
| 2983 |
.IX Item "--no-eh-frame-hdr" |
| 2984 |
.PD |
| 2985 |
Request (\fB\-\-eh\-frame\-hdr\fR) or suppress |
| 2986 |
(\fB\-\-no\-eh\-frame\-hdr\fR) the creation of \f(CW\*(C`.eh_frame_hdr\*(C'\fR |
| 2987 |
section and ELF \f(CW\*(C`PT_GNU_EH_FRAME\*(C'\fR segment header. |
| 2988 |
.IP \fB\-\-no\-ld\-generated\-unwind\-info\fR 4 |
| 2989 |
.IX Item "--no-ld-generated-unwind-info" |
| 2990 |
Request creation of \f(CW\*(C`.eh_frame\*(C'\fR unwind info for linker |
| 2991 |
generated code sections like PLT. This option is on by default |
| 2992 |
if linker generated unwind info is supported. |
| 2993 |
.IP \fB\-\-discard\-sframe\fR 4 |
| 2994 |
.IX Item "--discard-sframe" |
| 2995 |
Discard \f(CW\*(C`.sframe\*(C'\fR stack trace info from the output. This option also |
| 2996 |
prohibits the creation of SFrame stack trace data for linker generated code |
| 2997 |
sections like PLT. This option is off by default. |
| 2998 |
.IP \fB\-\-enable\-new\-dtags\fR 4 |
| 2999 |
.IX Item "--enable-new-dtags" |
| 3000 |
.PD 0 |
| 3001 |
.IP \fB\-\-disable\-new\-dtags\fR 4 |
| 3002 |
.IX Item "--disable-new-dtags" |
| 3003 |
.PD |
| 3004 |
This linker can create the new dynamic tags in ELF. But the older ELF |
| 3005 |
systems may not understand them. If you specify |
| 3006 |
\&\fB\-\-enable\-new\-dtags\fR, the new dynamic tags will be created as needed |
| 3007 |
and older dynamic tags will be omitted. |
| 3008 |
If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be |
| 3009 |
created. By default, the new dynamic tags are not created. Note that |
| 3010 |
those options are only available for ELF systems. |
| 3011 |
.IP \fB\-\-hash\-size=\fR\fInumber\fR 4 |
| 3012 |
.IX Item "--hash-size=number" |
| 3013 |
Set the default size of the linker's hash tables to a prime number |
| 3014 |
close to \fInumber\fR. Increasing this value can reduce the length of |
| 3015 |
time it takes the linker to perform its tasks, at the expense of |
| 3016 |
increasing the linker's memory requirements. Similarly reducing this |
| 3017 |
value can reduce the memory requirements at the expense of speed. |
| 3018 |
The default value is 4051 under normal circumstances and 1021 if the |
| 3019 |
\&\fB\-\-reduce\-memory\-overheads\fR command line option is used. |
| 3020 |
.IP \fB\-\-hash\-style=\fR\fIstyle\fR 4 |
| 3021 |
.IX Item "--hash-style=style" |
| 3022 |
Set the type of linker's hash table(s). \fIstyle\fR can be either |
| 3023 |
\&\f(CW\*(C`sysv\*(C'\fR for classic ELF \f(CW\*(C`.hash\*(C'\fR section, \f(CW\*(C`gnu\*(C'\fR for |
| 3024 |
new style GNU \f(CW\*(C`.gnu.hash\*(C'\fR section or \f(CW\*(C`both\*(C'\fR for both |
| 3025 |
the classic ELF \f(CW\*(C`.hash\*(C'\fR and new style GNU \f(CW\*(C`.gnu.hash\*(C'\fR |
| 3026 |
hash tables. The default depends upon how the linker was configured, |
| 3027 |
but for most Linux based systems it will be \f(CW\*(C`both\*(C'\fR. |
| 3028 |
.IP \fB\-\-compress\-debug\-sections=none\fR 4 |
| 3029 |
.IX Item "--compress-debug-sections=none" |
| 3030 |
.PD 0 |
| 3031 |
.IP \fB\-\-compress\-debug\-sections=zlib\fR 4 |
| 3032 |
.IX Item "--compress-debug-sections=zlib" |
| 3033 |
.IP \fB\-\-compress\-debug\-sections=zlib\-gnu\fR 4 |
| 3034 |
.IX Item "--compress-debug-sections=zlib-gnu" |
| 3035 |
.IP \fB\-\-compress\-debug\-sections=zlib\-gabi\fR 4 |
| 3036 |
.IX Item "--compress-debug-sections=zlib-gabi" |
| 3037 |
.IP \fB\-\-compress\-debug\-sections=zstd\fR 4 |
| 3038 |
.IX Item "--compress-debug-sections=zstd" |
| 3039 |
.PD |
| 3040 |
On ELF platforms, these options control how DWARF debug sections are |
| 3041 |
compressed using zlib. |
| 3042 |
.Sp |
| 3043 |
\&\fB\-\-compress\-debug\-sections=none\fR doesn't compress DWARF debug |
| 3044 |
sections. \fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses |
| 3045 |
DWARF debug sections and renames them to begin with \fB.zdebug\fR |
| 3046 |
instead of \fB.debug\fR. \fB\-\-compress\-debug\-sections=zlib\-gabi\fR |
| 3047 |
also compresses DWARF debug sections, but rather than renaming them it |
| 3048 |
sets the SHF_COMPRESSED flag in the sections' headers. |
| 3049 |
.Sp |
| 3050 |
The \fB\-\-compress\-debug\-sections=zlib\fR option is an alias for |
| 3051 |
\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR. |
| 3052 |
.Sp |
| 3053 |
\&\fB\-\-compress\-debug\-sections=zstd\fR compresses DWARF debug sections using |
| 3054 |
zstd. |
| 3055 |
.Sp |
| 3056 |
Note that this option overrides any compression in input debug |
| 3057 |
sections, so if a binary is linked with \fB\-\-compress\-debug\-sections=none\fR |
| 3058 |
for example, then any compressed debug sections in input files will be |
| 3059 |
uncompressed before they are copied into the output binary. |
| 3060 |
.Sp |
| 3061 |
The default compression behaviour varies depending upon the target |
| 3062 |
involved and the configure options used to build the toolchain. The |
| 3063 |
default can be determined by examining the output from the linker's |
| 3064 |
\&\fB\-\-help\fR option. |
| 3065 |
.IP \fB\-\-reduce\-memory\-overheads\fR 4 |
| 3066 |
.IX Item "--reduce-memory-overheads" |
| 3067 |
This option reduces memory requirements at ld runtime, at the expense of |
| 3068 |
linking speed. This was introduced to select the old O(n^2) algorithm |
| 3069 |
for link map file generation, rather than the new O(n) algorithm which uses |
| 3070 |
about 40% more memory for symbol storage. |
| 3071 |
.Sp |
| 3072 |
Another effect of the switch is to set the default hash table size to |
| 3073 |
1021, which again saves memory at the cost of lengthening the linker's |
| 3074 |
run time. This is not done however if the \fB\-\-hash\-size\fR switch |
| 3075 |
has been used. |
| 3076 |
.Sp |
| 3077 |
The \fB\-\-reduce\-memory\-overheads\fR switch may be also be used to |
| 3078 |
enable other tradeoffs in future versions of the linker. |
| 3079 |
.IP \fB\-\-max\-cache\-size=\fR\fIsize\fR 4 |
| 3080 |
.IX Item "--max-cache-size=size" |
| 3081 |
\&\fBld\fR normally caches the relocation information and symbol tables |
| 3082 |
of input files in memory with the unlimited size. This option sets the |
| 3083 |
maximum cache size to \fIsize\fR. Note \- if the |
| 3084 |
\&\fB\-\-no\-keep\-memory\fR command line option has been used then the |
| 3085 |
linker acts as if the maximum cache size has been set to 0 \- ie |
| 3086 |
nothing is retained. |
| 3087 |
.IP \fB\-\-build\-id\fR 4 |
| 3088 |
.IX Item "--build-id" |
| 3089 |
.PD 0 |
| 3090 |
.IP \fB\-\-build\-id=\fR\fIstyle\fR 4 |
| 3091 |
.IX Item "--build-id=style" |
| 3092 |
.PD |
| 3093 |
Request the creation of a \f(CW\*(C`.note.gnu.build\-id\*(C'\fR ELF note section |
| 3094 |
or a \f(CW\*(C`.buildid\*(C'\fR COFF section. The contents of the note are |
| 3095 |
unique bits identifying this linked file. \fIstyle\fR can be |
| 3096 |
\&\f(CW\*(C`uuid\*(C'\fR to use 128 random bits; \f(CW\*(C`sha1\*(C'\fR to use a 160\-bit |
| 3097 |
SHA1 hash, \f(CW\*(C`md5\*(C'\fR to use a 128\-bit MD5 hash, or \f(CW\*(C`xx\*(C'\fR |
| 3098 |
to use a 128\-bit XXHASH on the normative parts of the output |
| 3099 |
contents; or \f(CW\*(C`0x\fR\f(CIhexstring\fR\f(CW\*(C'\fR to use a chosen bit string |
| 3100 |
specified as an even number of hexadecimal digits (\f(CW\*(C`\-\*(C'\fR and |
| 3101 |
\&\f(CW\*(C`:\*(C'\fR characters between digit pairs are ignored). If \fIstyle\fR |
| 3102 |
is omitted, \f(CW\*(C`sha1\*(C'\fR is used. |
| 3103 |
.Sp |
| 3104 |
The \f(CW\*(C`md5\*(C'\fR, \f(CW\*(C`sha1\*(C'\fR, and \f(CW\*(C`xx\*(C'\fR styles produces an |
| 3105 |
identifier that is always the same in an identical output file, but |
| 3106 |
are almost certainly unique among all nonidentical output files. It |
| 3107 |
is not intended to be compared as a checksum for the file's contents. |
| 3108 |
A linked file may be changed later by other tools, but the build ID |
| 3109 |
bit string identifying the original linked file does not change. |
| 3110 |
.Sp |
| 3111 |
Passing \f(CW\*(C`none\*(C'\fR for \fIstyle\fR disables the setting from any |
| 3112 |
\&\f(CW\*(C`\-\-build\-id\*(C'\fR options earlier on the command line. |
| 3113 |
.IP \fB\-\-package\-metadata=\fR\fIJSON\fR 4 |
| 3114 |
.IX Item "--package-metadata=JSON" |
| 3115 |
Request the creation of a \f(CW\*(C`.note.package\*(C'\fR ELF note section. The |
| 3116 |
contents of the note are in JSON format, as per the package metadata |
| 3117 |
specification. For more information see: |
| 3118 |
https://systemd.io/ELF_PACKAGE_METADATA/ |
| 3119 |
The JSON argument support percent-encoding and following %[string] |
| 3120 |
(where string refers to the name in HTML's Named Character References) |
| 3121 |
encoding: \fB%[comma]\fR for \fB,\fR, \fB%[lbrace]\fR for \fB{\fR, |
| 3122 |
\&\fB%[quot]\fR for \fB"\fR, \fB%[rbrace]\fR for \fB}\fR, and |
| 3123 |
\&\fB%[space]\fR for space character. |
| 3124 |
If the JSON argument is missing/empty then this will disable the |
| 3125 |
creation of the metadata note, if one had been enabled by an earlier |
| 3126 |
occurrence of the \-\-package\-metadata option. |
| 3127 |
If the linker has been built with libjansson, then the JSON string |
| 3128 |
will be validated. |
| 3129 |
.PP |
| 3130 |
The i386 PE linker supports the \fB\-shared\fR option, which causes |
| 3131 |
the output to be a dynamically linked library (DLL) instead of a |
| 3132 |
normal executable. You should name the output \f(CW\*(C`*.dll\*(C'\fR when you |
| 3133 |
use this option. In addition, the linker fully supports the standard |
| 3134 |
\&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line |
| 3135 |
like an object file (in fact, it should precede archives it exports |
| 3136 |
symbols from, to ensure that they get linked in, just like a normal |
| 3137 |
object file). |
| 3138 |
.PP |
| 3139 |
In addition to the options common to all targets, the i386 PE linker |
| 3140 |
support additional command-line options that are specific to the i386 |
| 3141 |
PE target. Options that take values may be separated from their |
| 3142 |
values by either a space or an equals sign. |
| 3143 |
.IP \fB\-\-add\-stdcall\-alias\fR 4 |
| 3144 |
.IX Item "--add-stdcall-alias" |
| 3145 |
If given, symbols with a stdcall suffix (@\fInn\fR) will be exported |
| 3146 |
as-is and also with the suffix stripped. |
| 3147 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3148 |
.IP "\fB\-\-base\-file\fR \fIfile\fR" 4 |
| 3149 |
.IX Item "--base-file file" |
| 3150 |
Use \fIfile\fR as the name of a file in which to save the base |
| 3151 |
addresses of all the relocations needed for generating DLLs with |
| 3152 |
\&\fIdlltool\fR. |
| 3153 |
[This is an i386 PE specific option] |
| 3154 |
.IP \fB\-\-dll\fR 4 |
| 3155 |
.IX Item "--dll" |
| 3156 |
Create a DLL instead of a regular executable. You may also use |
| 3157 |
\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR |
| 3158 |
file. |
| 3159 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3160 |
.IP \fB\-\-enable\-long\-section\-names\fR 4 |
| 3161 |
.IX Item "--enable-long-section-names" |
| 3162 |
.PD 0 |
| 3163 |
.IP \fB\-\-disable\-long\-section\-names\fR 4 |
| 3164 |
.IX Item "--disable-long-section-names" |
| 3165 |
.PD |
| 3166 |
The PE variants of the COFF object format add an extension that permits |
| 3167 |
the use of section names longer than eight characters, the normal limit |
| 3168 |
for COFF. By default, these names are only allowed in object files, as |
| 3169 |
fully-linked executable images do not carry the COFF string table required |
| 3170 |
to support the longer names. As a GNU extension, it is possible to |
| 3171 |
allow their use in executable images as well, or to (probably pointlessly!) |
| 3172 |
disallow it in object files, by using these two options. Executable images |
| 3173 |
generated with these long section names are slightly non-standard, carrying |
| 3174 |
as they do a string table, and may generate confusing output when examined |
| 3175 |
with non-GNU PE-aware tools, such as file viewers and dumpers. However, |
| 3176 |
GDB relies on the use of PE long section names to find Dwarf\-2 debug |
| 3177 |
information sections in an executable image at runtime, and so if neither |
| 3178 |
option is specified on the command-line, \fBld\fR will enable long |
| 3179 |
section names, overriding the default and technically correct behaviour, |
| 3180 |
when it finds the presence of debug information while linking an executable |
| 3181 |
image and not stripping symbols. |
| 3182 |
[This option is valid for all PE targeted ports of the linker] |
| 3183 |
.IP \fB\-\-enable\-stdcall\-fixup\fR 4 |
| 3184 |
.IX Item "--enable-stdcall-fixup" |
| 3185 |
.PD 0 |
| 3186 |
.IP \fB\-\-disable\-stdcall\-fixup\fR 4 |
| 3187 |
.IX Item "--disable-stdcall-fixup" |
| 3188 |
.PD |
| 3189 |
If the link finds a symbol that it cannot resolve, it will attempt to |
| 3190 |
do "fuzzy linking" by looking for another defined symbol that differs |
| 3191 |
only in the format of the symbol name (cdecl vs stdcall) and will |
| 3192 |
resolve that symbol by linking to the match. For example, the |
| 3193 |
undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function |
| 3194 |
\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked |
| 3195 |
to the function \f(CW\*(C`_bar\*(C'\fR. When the linker does this, it prints a |
| 3196 |
warning, since it normally should have failed to link, but sometimes |
| 3197 |
import libraries generated from third-party dlls may need this feature |
| 3198 |
to be usable. If you specify \fB\-\-enable\-stdcall\-fixup\fR, this |
| 3199 |
feature is fully enabled and warnings are not printed. If you specify |
| 3200 |
\&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such |
| 3201 |
mismatches are considered to be errors. |
| 3202 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3203 |
.IP \fB\-\-leading\-underscore\fR 4 |
| 3204 |
.IX Item "--leading-underscore" |
| 3205 |
.PD 0 |
| 3206 |
.IP \fB\-\-no\-leading\-underscore\fR 4 |
| 3207 |
.IX Item "--no-leading-underscore" |
| 3208 |
.PD |
| 3209 |
For most targets default symbol-prefix is an underscore and is defined |
| 3210 |
in target's description. By this option it is possible to |
| 3211 |
disable/enable the default underscore symbol-prefix. |
| 3212 |
.IP \fB\-\-export\-all\-symbols\fR 4 |
| 3213 |
.IX Item "--export-all-symbols" |
| 3214 |
If given, all global symbols in the objects used to build a DLL will |
| 3215 |
be exported by the DLL. Note that this is the default if there |
| 3216 |
otherwise wouldn't be any exported symbols. When symbols are |
| 3217 |
explicitly exported via DEF files or implicitly exported via function |
| 3218 |
attributes, the default is to not export anything else unless this |
| 3219 |
option is given. Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR, |
| 3220 |
\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and |
| 3221 |
\&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically |
| 3222 |
exported. Also, symbols imported from other DLLs will not be |
| 3223 |
re-exported, nor will symbols specifying the DLL's internal layout |
| 3224 |
such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with |
| 3225 |
\&\f(CW\*(C`_iname\*(C'\fR. In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR, |
| 3226 |
\&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported. |
| 3227 |
Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will |
| 3228 |
not be exported, to help with C++ DLLs. Finally, there is an |
| 3229 |
extensive list of cygwin-private symbols that are not exported |
| 3230 |
(obviously, this applies on when building DLLs for cygwin targets). |
| 3231 |
These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR, |
| 3232 |
\&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_dll_entry@12\*(C'\fR, |
| 3233 |
\&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR, |
| 3234 |
\&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR, |
| 3235 |
\&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR. |
| 3236 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3237 |
.IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4 |
| 3238 |
.IX Item "--exclude-symbols symbol,symbol,..." |
| 3239 |
Specifies a list of symbols which should not be automatically |
| 3240 |
exported. The symbol names may be delimited by commas or colons. |
| 3241 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3242 |
.IP \fB\-\-exclude\-all\-symbols\fR 4 |
| 3243 |
.IX Item "--exclude-all-symbols" |
| 3244 |
Specifies no symbols should be automatically exported. |
| 3245 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3246 |
.IP \fB\-\-file\-alignment\fR 4 |
| 3247 |
.IX Item "--file-alignment" |
| 3248 |
Specify the file alignment. Sections in the file will always begin at |
| 3249 |
file offsets which are multiples of this number. This defaults to |
| 3250 |
512. |
| 3251 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3252 |
.IP "\fB\-\-heap\fR \fIreserve\fR" 4 |
| 3253 |
.IX Item "--heap reserve" |
| 3254 |
.PD 0 |
| 3255 |
.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 |
| 3256 |
.IX Item "--heap reserve,commit" |
| 3257 |
.PD |
| 3258 |
Specify the number of bytes of memory to reserve (and optionally commit) |
| 3259 |
to be used as heap for this program. The default is 1MB reserved, 4K |
| 3260 |
committed. |
| 3261 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3262 |
.IP \fB\-\-kill\-at\fR 4 |
| 3263 |
.IX Item "--kill-at" |
| 3264 |
If given, the stdcall suffixes (@\fInn\fR) will be stripped from |
| 3265 |
symbols before they are exported. |
| 3266 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3267 |
.IP \fB\-\-large\-address\-aware\fR 4 |
| 3268 |
.IX Item "--large-address-aware" |
| 3269 |
If given, the appropriate bit in the "Characteristics" field of the COFF |
| 3270 |
header is set to indicate that this executable supports virtual addresses |
| 3271 |
greater than 2 gigabytes. This should be used in conjunction with the /3GB |
| 3272 |
or /USERVA=\fIvalue\fR megabytes switch in the "[operating systems]" |
| 3273 |
section of the BOOT.INI. Otherwise, this bit has no effect. |
| 3274 |
[This option is specific to PE targeted ports of the linker] |
| 3275 |
.IP \fB\-\-disable\-large\-address\-aware\fR 4 |
| 3276 |
.IX Item "--disable-large-address-aware" |
| 3277 |
Reverts the effect of a previous \fB\-\-large\-address\-aware\fR option. |
| 3278 |
This is useful if \fB\-\-large\-address\-aware\fR is always set by the compiler |
| 3279 |
driver (e.g. Cygwin gcc) and the executable does not support virtual |
| 3280 |
addresses greater than 2 gigabytes. |
| 3281 |
[This option is specific to PE targeted ports of the linker] |
| 3282 |
.IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4 |
| 3283 |
.IX Item "--major-image-version value" |
| 3284 |
Sets the major number of the "image version". Defaults to 1. |
| 3285 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3286 |
.IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4 |
| 3287 |
.IX Item "--major-os-version value" |
| 3288 |
Sets the major number of the "os version". Defaults to 4. |
| 3289 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3290 |
.IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4 |
| 3291 |
.IX Item "--major-subsystem-version value" |
| 3292 |
Sets the major number of the "subsystem version". Defaults to 4. |
| 3293 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3294 |
.IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4 |
| 3295 |
.IX Item "--minor-image-version value" |
| 3296 |
Sets the minor number of the "image version". Defaults to 0. |
| 3297 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3298 |
.IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4 |
| 3299 |
.IX Item "--minor-os-version value" |
| 3300 |
Sets the minor number of the "os version". Defaults to 0. |
| 3301 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3302 |
.IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4 |
| 3303 |
.IX Item "--minor-subsystem-version value" |
| 3304 |
Sets the minor number of the "subsystem version". Defaults to 0. |
| 3305 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3306 |
.IP "\fB\-\-output\-def\fR \fIfile\fR" 4 |
| 3307 |
.IX Item "--output-def file" |
| 3308 |
The linker will create the file \fIfile\fR which will contain a DEF |
| 3309 |
file corresponding to the DLL the linker is generating. This DEF file |
| 3310 |
(which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import |
| 3311 |
library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to |
| 3312 |
automatically or implicitly exported symbols. |
| 3313 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3314 |
.IP \fB\-\-enable\-auto\-image\-base\fR 4 |
| 3315 |
.IX Item "--enable-auto-image-base" |
| 3316 |
.PD 0 |
| 3317 |
.IP \fB\-\-enable\-auto\-image\-base=\fR\fIvalue\fR 4 |
| 3318 |
.IX Item "--enable-auto-image-base=value" |
| 3319 |
.PD |
| 3320 |
Automatically choose the image base for DLLs, optionally starting with base |
| 3321 |
\&\fIvalue\fR, unless one is specified using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument. |
| 3322 |
By using a hash generated from the dllname to create unique image bases |
| 3323 |
for each DLL, in-memory collisions and relocations which can delay program |
| 3324 |
execution are avoided. |
| 3325 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3326 |
.IP \fB\-\-disable\-auto\-image\-base\fR 4 |
| 3327 |
.IX Item "--disable-auto-image-base" |
| 3328 |
Do not automatically generate a unique image base. If there is no |
| 3329 |
user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform |
| 3330 |
default. |
| 3331 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3332 |
.IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4 |
| 3333 |
.IX Item "--dll-search-prefix string" |
| 3334 |
When linking dynamically to a dll without an import library, |
| 3335 |
search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to |
| 3336 |
\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behaviour allows easy distinction |
| 3337 |
between DLLs built for the various "subplatforms": native, cygwin, |
| 3338 |
uwin, pw, etc. For instance, cygwin DLLs typically use |
| 3339 |
\&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR. |
| 3340 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3341 |
.IP \fB\-\-enable\-auto\-import\fR 4 |
| 3342 |
.IX Item "--enable-auto-import" |
| 3343 |
Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for |
| 3344 |
DATA imports from DLLs, thus making it possible to bypass the dllimport |
| 3345 |
mechanism on the user side and to reference unmangled symbol names. |
| 3346 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3347 |
.Sp |
| 3348 |
The following remarks pertain to the original implementation of the |
| 3349 |
feature and are obsolete nowadays for Cygwin and MinGW targets. |
| 3350 |
.Sp |
| 3351 |
Note: Use of the 'auto\-import' extension will cause the text section |
| 3352 |
of the image file to be made writable. This does not conform to the |
| 3353 |
PE-COFF format specification published by Microsoft. |
| 3354 |
.Sp |
| 3355 |
Note \- use of the 'auto\-import' extension will also cause read only |
| 3356 |
data which would normally be placed into the .rdata section to be |
| 3357 |
placed into the .data section instead. This is in order to work |
| 3358 |
around a problem with consts that is described here: |
| 3359 |
http://www.cygwin.com/ml/cygwin/2004\-09/msg01101.html |
| 3360 |
.Sp |
| 3361 |
Using 'auto\-import' generally will 'just work' \-\- but sometimes you may |
| 3362 |
see this message: |
| 3363 |
.Sp |
| 3364 |
"variable '<var>' can't be auto-imported. Please read the |
| 3365 |
documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details." |
| 3366 |
.Sp |
| 3367 |
This message occurs when some (sub)expression accesses an address |
| 3368 |
ultimately given by the sum of two constants (Win32 import tables only |
| 3369 |
allow one). Instances where this may occur include accesses to member |
| 3370 |
fields of struct variables imported from a DLL, as well as using a |
| 3371 |
constant index into an array variable imported from a DLL. Any |
| 3372 |
multiword variable (arrays, structs, long long, etc) may trigger |
| 3373 |
this error condition. However, regardless of the exact data type |
| 3374 |
of the offending exported variable, ld will always detect it, issue |
| 3375 |
the warning, and exit. |
| 3376 |
.Sp |
| 3377 |
There are several ways to address this difficulty, regardless of the |
| 3378 |
data type of the exported variable: |
| 3379 |
.Sp |
| 3380 |
One way is to use \-\-enable\-runtime\-pseudo\-reloc switch. This leaves the task |
| 3381 |
of adjusting references in your client code for runtime environment, so |
| 3382 |
this method works only when runtime environment supports this feature. |
| 3383 |
.Sp |
| 3384 |
A second solution is to force one of the 'constants' to be a variable \-\- |
| 3385 |
that is, unknown and un-optimizable at compile time. For arrays, |
| 3386 |
there are two possibilities: a) make the indexee (the array's address) |
| 3387 |
a variable, or b) make the 'constant' index a variable. Thus: |
| 3388 |
.Sp |
| 3389 |
.Vb 3 |
| 3390 |
\& extern type extern_array[]; |
| 3391 |
\& extern_array[1] \-\-> |
| 3392 |
\& { volatile type *t=extern_array; t[1] } |
| 3393 |
.Ve |
| 3394 |
.Sp |
| 3395 |
or |
| 3396 |
.Sp |
| 3397 |
.Vb 3 |
| 3398 |
\& extern type extern_array[]; |
| 3399 |
\& extern_array[1] \-\-> |
| 3400 |
\& { volatile int t=1; extern_array[t] } |
| 3401 |
.Ve |
| 3402 |
.Sp |
| 3403 |
For structs (and most other multiword data types) the only option |
| 3404 |
is to make the struct itself (or the long long, or the ...) variable: |
| 3405 |
.Sp |
| 3406 |
.Vb 3 |
| 3407 |
\& extern struct s extern_struct; |
| 3408 |
\& extern_struct.field \-\-> |
| 3409 |
\& { volatile struct s *t=&extern_struct; t\->field } |
| 3410 |
.Ve |
| 3411 |
.Sp |
| 3412 |
or |
| 3413 |
.Sp |
| 3414 |
.Vb 3 |
| 3415 |
\& extern long long extern_ll; |
| 3416 |
\& extern_ll \-\-> |
| 3417 |
\& { volatile long long * local_ll=&extern_ll; *local_ll } |
| 3418 |
.Ve |
| 3419 |
.Sp |
| 3420 |
A third method of dealing with this difficulty is to abandon |
| 3421 |
\&'auto\-import' for the offending symbol and mark it with |
| 3422 |
\&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR. However, in practice that |
| 3423 |
requires using compile-time #defines to indicate whether you are |
| 3424 |
building a DLL, building client code that will link to the DLL, or |
| 3425 |
merely building/linking to a static library. In making the choice |
| 3426 |
between the various methods of resolving the 'direct address with |
| 3427 |
constant offset' problem, you should consider typical real-world usage: |
| 3428 |
.Sp |
| 3429 |
Original: |
| 3430 |
.Sp |
| 3431 |
.Vb 7 |
| 3432 |
\& \-\-foo.h |
| 3433 |
\& extern int arr[]; |
| 3434 |
\& \-\-foo.c |
| 3435 |
\& #include "foo.h" |
| 3436 |
\& void main(int argc, char **argv){ |
| 3437 |
\& printf("%d\en",arr[1]); |
| 3438 |
\& } |
| 3439 |
.Ve |
| 3440 |
.Sp |
| 3441 |
Solution 1: |
| 3442 |
.Sp |
| 3443 |
.Vb 9 |
| 3444 |
\& \-\-foo.h |
| 3445 |
\& extern int arr[]; |
| 3446 |
\& \-\-foo.c |
| 3447 |
\& #include "foo.h" |
| 3448 |
\& void main(int argc, char **argv){ |
| 3449 |
\& /* This workaround is for win32 and cygwin; do not "optimize" */ |
| 3450 |
\& volatile int *parr = arr; |
| 3451 |
\& printf("%d\en",parr[1]); |
| 3452 |
\& } |
| 3453 |
.Ve |
| 3454 |
.Sp |
| 3455 |
Solution 2: |
| 3456 |
.Sp |
| 3457 |
.Vb 10 |
| 3458 |
\& \-\-foo.h |
| 3459 |
\& /* Note: auto\-export is assumed (no _\|_declspec(dllexport)) */ |
| 3460 |
\& #if (defined(_WIN32) || defined(_\|_CYGWIN_\|_)) && \e |
| 3461 |
\& !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) |
| 3462 |
\& #define FOO_IMPORT _\|_declspec(dllimport) |
| 3463 |
\& #else |
| 3464 |
\& #define FOO_IMPORT |
| 3465 |
\& #endif |
| 3466 |
\& extern FOO_IMPORT int arr[]; |
| 3467 |
\& \-\-foo.c |
| 3468 |
\& #include "foo.h" |
| 3469 |
\& void main(int argc, char **argv){ |
| 3470 |
\& printf("%d\en",arr[1]); |
| 3471 |
\& } |
| 3472 |
.Ve |
| 3473 |
.Sp |
| 3474 |
A fourth way to avoid this problem is to re-code your |
| 3475 |
library to use a functional interface rather than a data interface |
| 3476 |
for the offending variables (e.g. \fBset_foo()\fR and \fBget_foo()\fR accessor |
| 3477 |
functions). |
| 3478 |
.IP \fB\-\-disable\-auto\-import\fR 4 |
| 3479 |
.IX Item "--disable-auto-import" |
| 3480 |
Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to |
| 3481 |
\&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for DATA imports from DLLs. |
| 3482 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3483 |
.IP \fB\-\-enable\-runtime\-pseudo\-reloc\fR 4 |
| 3484 |
.IX Item "--enable-runtime-pseudo-reloc" |
| 3485 |
If your code contains expressions described in \-\-enable\-auto\-import section, |
| 3486 |
that is, DATA imports from DLL with non-zero offset, this switch will create |
| 3487 |
a vector of 'runtime pseudo relocations' which can be used by runtime |
| 3488 |
environment to adjust references to such data in your client code. |
| 3489 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3490 |
.IP \fB\-\-disable\-runtime\-pseudo\-reloc\fR 4 |
| 3491 |
.IX Item "--disable-runtime-pseudo-reloc" |
| 3492 |
Do not create pseudo relocations for non-zero offset DATA imports from DLLs. |
| 3493 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3494 |
.IP \fB\-\-enable\-extra\-pe\-debug\fR 4 |
| 3495 |
.IX Item "--enable-extra-pe-debug" |
| 3496 |
Show additional debug info related to auto-import symbol thunking. |
| 3497 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3498 |
.IP \fB\-\-section\-alignment\fR 4 |
| 3499 |
.IX Item "--section-alignment" |
| 3500 |
Sets the section alignment. Sections in memory will always begin at |
| 3501 |
addresses which are a multiple of this number. Defaults to 0x1000. |
| 3502 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3503 |
.IP "\fB\-\-stack\fR \fIreserve\fR" 4 |
| 3504 |
.IX Item "--stack reserve" |
| 3505 |
.PD 0 |
| 3506 |
.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 |
| 3507 |
.IX Item "--stack reserve,commit" |
| 3508 |
.PD |
| 3509 |
Specify the number of bytes of memory to reserve (and optionally commit) |
| 3510 |
to be used as stack for this program. The default is 2MB reserved, 4K |
| 3511 |
committed. |
| 3512 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3513 |
.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4 |
| 3514 |
.IX Item "--subsystem which" |
| 3515 |
.PD 0 |
| 3516 |
.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4 |
| 3517 |
.IX Item "--subsystem which:major" |
| 3518 |
.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4 |
| 3519 |
.IX Item "--subsystem which:major.minor" |
| 3520 |
.PD |
| 3521 |
Specifies the subsystem under which your program will execute. The |
| 3522 |
legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR, |
| 3523 |
\&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR. You may optionally set |
| 3524 |
the subsystem version also. Numeric values are also accepted for |
| 3525 |
\&\fIwhich\fR. |
| 3526 |
[This option is specific to the i386 PE targeted port of the linker] |
| 3527 |
.Sp |
| 3528 |
The following options set flags in the \f(CW\*(C`DllCharacteristics\*(C'\fR field |
| 3529 |
of the PE file header: |
| 3530 |
[These options are specific to PE targeted ports of the linker] |
| 3531 |
.IP \fB\-\-high\-entropy\-va\fR 4 |
| 3532 |
.IX Item "--high-entropy-va" |
| 3533 |
.PD 0 |
| 3534 |
.IP \fB\-\-disable\-high\-entropy\-va\fR 4 |
| 3535 |
.IX Item "--disable-high-entropy-va" |
| 3536 |
.PD |
| 3537 |
Image is compatible with 64\-bit address space layout randomization |
| 3538 |
(ASLR). This option is enabled by default for 64\-bit PE images in |
| 3539 |
MinGW targets. |
| 3540 |
.Sp |
| 3541 |
This option also implies \fB\-\-dynamicbase\fR and |
| 3542 |
\&\fB\-\-enable\-reloc\-section\fR. |
| 3543 |
.IP \fB\-\-dynamicbase\fR 4 |
| 3544 |
.IX Item "--dynamicbase" |
| 3545 |
.PD 0 |
| 3546 |
.IP \fB\-\-disable\-dynamicbase\fR 4 |
| 3547 |
.IX Item "--disable-dynamicbase" |
| 3548 |
.PD |
| 3549 |
The image base address may be relocated using address space layout |
| 3550 |
randomization (ASLR). This feature was introduced with MS Windows |
| 3551 |
Vista for i386 PE targets. This option is enabled by default for MinGW |
| 3552 |
targets but can be disabled via the \fB\-\-disable\-dynamicbase\fR |
| 3553 |
option. This option also implies \fB\-\-enable\-reloc\-section\fR. |
| 3554 |
.IP \fB\-\-forceinteg\fR 4 |
| 3555 |
.IX Item "--forceinteg" |
| 3556 |
.PD 0 |
| 3557 |
.IP \fB\-\-disable\-forceinteg\fR 4 |
| 3558 |
.IX Item "--disable-forceinteg" |
| 3559 |
.PD |
| 3560 |
Code integrity checks are enforced. This option is disabled by |
| 3561 |
default. |
| 3562 |
.IP \fB\-\-nxcompat\fR 4 |
| 3563 |
.IX Item "--nxcompat" |
| 3564 |
.PD 0 |
| 3565 |
.IP \fB\-\-disable\-nxcompat\fR 4 |
| 3566 |
.IX Item "--disable-nxcompat" |
| 3567 |
.PD |
| 3568 |
The image is compatible with the Data Execution Prevention. |
| 3569 |
This feature was introduced with MS Windows XP SP2 for i386 PE |
| 3570 |
targets. The option is enabled by default for MinGW targets. |
| 3571 |
.IP \fB\-\-no\-isolation\fR 4 |
| 3572 |
.IX Item "--no-isolation" |
| 3573 |
.PD 0 |
| 3574 |
.IP \fB\-\-disable\-no\-isolation\fR 4 |
| 3575 |
.IX Item "--disable-no-isolation" |
| 3576 |
.PD |
| 3577 |
Although the image understands isolation, do not isolate the image. |
| 3578 |
This option is disabled by default. |
| 3579 |
.IP \fB\-\-no\-seh\fR 4 |
| 3580 |
.IX Item "--no-seh" |
| 3581 |
.PD 0 |
| 3582 |
.IP \fB\-\-disable\-no\-seh\fR 4 |
| 3583 |
.IX Item "--disable-no-seh" |
| 3584 |
.PD |
| 3585 |
The image does not use SEH. No SE handler may be called from |
| 3586 |
this image. This option is disabled by default. |
| 3587 |
.IP \fB\-\-no\-bind\fR 4 |
| 3588 |
.IX Item "--no-bind" |
| 3589 |
.PD 0 |
| 3590 |
.IP \fB\-\-disable\-no\-bind\fR 4 |
| 3591 |
.IX Item "--disable-no-bind" |
| 3592 |
.PD |
| 3593 |
Do not bind this image. This option is disabled by default. |
| 3594 |
.IP \fB\-\-wdmdriver\fR 4 |
| 3595 |
.IX Item "--wdmdriver" |
| 3596 |
.PD 0 |
| 3597 |
.IP \fB\-\-disable\-wdmdriver\fR 4 |
| 3598 |
.IX Item "--disable-wdmdriver" |
| 3599 |
.PD |
| 3600 |
The driver uses the MS Windows Driver Model. This option is disabled |
| 3601 |
by default. |
| 3602 |
.IP \fB\-\-tsaware\fR 4 |
| 3603 |
.IX Item "--tsaware" |
| 3604 |
.PD 0 |
| 3605 |
.IP \fB\-\-disable\-tsaware\fR 4 |
| 3606 |
.IX Item "--disable-tsaware" |
| 3607 |
.PD |
| 3608 |
The image is Terminal Server aware. This option is disabled by |
| 3609 |
default. |
| 3610 |
.IP \fB\-\-insert\-timestamp\fR 4 |
| 3611 |
.IX Item "--insert-timestamp" |
| 3612 |
.PD 0 |
| 3613 |
.IP \fB\-\-no\-insert\-timestamp\fR 4 |
| 3614 |
.IX Item "--no-insert-timestamp" |
| 3615 |
.PD |
| 3616 |
Insert a real timestamp into the image. This is the default behaviour |
| 3617 |
as it matches legacy code and it means that the image will work with |
| 3618 |
other, proprietary tools. The problem with this default is that it |
| 3619 |
will result in slightly different images being produced each time the |
| 3620 |
same sources are linked. The option \fB\-\-no\-insert\-timestamp\fR |
| 3621 |
can be used to insert a zero value for the timestamp, this ensuring |
| 3622 |
that binaries produced from identical sources will compare |
| 3623 |
identically. |
| 3624 |
.Sp |
| 3625 |
If \fB\-\-insert\-timestamp\fR is active then the time inserted is |
| 3626 |
either the time that the linking takes place or, if the |
| 3627 |
\&\f(CW\*(C`SOURCE_DATE_EPOCH\*(C'\fR environment variable is defined, the number |
| 3628 |
of seconds since Unix epoch as specified by that variable. |
| 3629 |
.IP \fB\-\-enable\-reloc\-section\fR 4 |
| 3630 |
.IX Item "--enable-reloc-section" |
| 3631 |
.PD 0 |
| 3632 |
.IP \fB\-\-disable\-reloc\-section\fR 4 |
| 3633 |
.IX Item "--disable-reloc-section" |
| 3634 |
.PD |
| 3635 |
Create the base relocation table, which is necessary if the image |
| 3636 |
is loaded at a different image base than specified in the PE header. |
| 3637 |
This option is enabled by default. |
| 3638 |
.PP |
| 3639 |
The C6X uClinux target uses a binary format called DSBT to support shared |
| 3640 |
libraries. Each shared library in the system needs to have a unique index; |
| 3641 |
all executables use an index of 0. |
| 3642 |
.IP "\fB\-\-dsbt\-size\fR \fIsize\fR" 4 |
| 3643 |
.IX Item "--dsbt-size size" |
| 3644 |
This option sets the number of entries in the DSBT of the current executable |
| 3645 |
or shared library to \fIsize\fR. The default is to create a table with 64 |
| 3646 |
entries. |
| 3647 |
.IP "\fB\-\-dsbt\-index\fR \fIindex\fR" 4 |
| 3648 |
.IX Item "--dsbt-index index" |
| 3649 |
This option sets the DSBT index of the current executable or shared library |
| 3650 |
to \fIindex\fR. The default is 0, which is appropriate for generating |
| 3651 |
executables. If a shared library is generated with a DSBT index of 0, the |
| 3652 |
\&\f(CW\*(C`R_C6000_DSBT_INDEX\*(C'\fR relocs are copied into the output file. |
| 3653 |
.Sp |
| 3654 |
The \fB\-\-no\-merge\-exidx\-entries\fR switch disables the merging of adjacent |
| 3655 |
exidx entries in frame unwind info. |
| 3656 |
.IP \fB\-\-branch\-stub\fR 4 |
| 3657 |
.IX Item "--branch-stub" |
| 3658 |
This option enables linker branch relaxation by inserting branch stub |
| 3659 |
sections when needed to extend the range of branches. This option is |
| 3660 |
usually not required since C\-SKY supports branch and call instructions that |
| 3661 |
can access the full memory range and branch relaxation is normally handled by |
| 3662 |
the compiler or assembler. |
| 3663 |
.IP \fB\-\-stub\-group\-size=\fR\fIN\fR 4 |
| 3664 |
.IX Item "--stub-group-size=N" |
| 3665 |
This option allows finer control of linker branch stub creation. |
| 3666 |
It sets the maximum size of a group of input sections that can |
| 3667 |
be handled by one stub section. A negative value of \fIN\fR locates |
| 3668 |
stub sections after their branches, while a positive value allows stub |
| 3669 |
sections to appear either before or after the branches. Values of |
| 3670 |
\&\fB1\fR or \fB\-1\fR indicate that the |
| 3671 |
linker should choose suitable defaults. |
| 3672 |
.PP |
| 3673 |
The 68HC11 and 68HC12 linkers support specific options to control the |
| 3674 |
memory bank switching mapping and trampoline code generation. |
| 3675 |
.IP \fB\-\-no\-trampoline\fR 4 |
| 3676 |
.IX Item "--no-trampoline" |
| 3677 |
This option disables the generation of trampoline. By default a trampoline |
| 3678 |
is generated for each far function which is called using a \f(CW\*(C`jsr\*(C'\fR |
| 3679 |
instruction (this happens when a pointer to a far function is taken). |
| 3680 |
.IP "\fB\-\-bank\-window\fR \fIname\fR" 4 |
| 3681 |
.IX Item "--bank-window name" |
| 3682 |
This option indicates to the linker the name of the memory region in |
| 3683 |
the \fBMEMORY\fR specification that describes the memory bank window. |
| 3684 |
The definition of such region is then used by the linker to compute |
| 3685 |
paging and addresses within the memory window. |
| 3686 |
.PP |
| 3687 |
The following options are supported to control handling of GOT generation |
| 3688 |
when linking for 68K targets. |
| 3689 |
.IP \fB\-\-got=\fR\fItype\fR 4 |
| 3690 |
.IX Item "--got=type" |
| 3691 |
This option tells the linker which GOT generation scheme to use. |
| 3692 |
\&\fItype\fR should be one of \fBsingle\fR, \fBnegative\fR, |
| 3693 |
\&\fBmultigot\fR or \fBtarget\fR. For more information refer to the |
| 3694 |
Info entry for \fIld\fR. |
| 3695 |
.PP |
| 3696 |
The following options are supported to control microMIPS instruction |
| 3697 |
generation and branch relocation checks for ISA mode transitions when |
| 3698 |
linking for MIPS targets. |
| 3699 |
.IP \fB\-\-insn32\fR 4 |
| 3700 |
.IX Item "--insn32" |
| 3701 |
.PD 0 |
| 3702 |
.IP \fB\-\-no\-insn32\fR 4 |
| 3703 |
.IX Item "--no-insn32" |
| 3704 |
.PD |
| 3705 |
These options control the choice of microMIPS instructions used in code |
| 3706 |
generated by the linker, such as that in the PLT or lazy binding stubs, |
| 3707 |
or in relaxation. If \fB\-\-insn32\fR is used, then the linker only uses |
| 3708 |
32\-bit instruction encodings. By default or if \fB\-\-no\-insn32\fR is |
| 3709 |
used, all instruction encodings are used, including 16\-bit ones where |
| 3710 |
possible. |
| 3711 |
.IP \fB\-\-ignore\-branch\-isa\fR 4 |
| 3712 |
.IX Item "--ignore-branch-isa" |
| 3713 |
.PD 0 |
| 3714 |
.IP \fB\-\-no\-ignore\-branch\-isa\fR 4 |
| 3715 |
.IX Item "--no-ignore-branch-isa" |
| 3716 |
.PD |
| 3717 |
These options control branch relocation checks for invalid ISA mode |
| 3718 |
transitions. If \fB\-\-ignore\-branch\-isa\fR is used, then the linker |
| 3719 |
accepts any branch relocations and any ISA mode transition required |
| 3720 |
is lost in relocation calculation, except for some cases of \f(CW\*(C`BAL\*(C'\fR |
| 3721 |
instructions which meet relaxation conditions and are converted to |
| 3722 |
equivalent \f(CW\*(C`JALX\*(C'\fR instructions as the associated relocation is |
| 3723 |
calculated. By default or if \fB\-\-no\-ignore\-branch\-isa\fR is used |
| 3724 |
a check is made causing the loss of an ISA mode transition to produce |
| 3725 |
an error. |
| 3726 |
.IP \fB\-\-compact\-branches\fR 4 |
| 3727 |
.IX Item "--compact-branches" |
| 3728 |
.PD 0 |
| 3729 |
.IP \fB\-\-no\-compact\-branches\fR 4 |
| 3730 |
.IX Item "--no-compact-branches" |
| 3731 |
.PD |
| 3732 |
These options control the generation of compact instructions by the linker |
| 3733 |
in the PLT entries for MIPS R6. |
| 3734 |
.PP |
| 3735 |
For the pdp11\-aout target, three variants of the output format can be |
| 3736 |
produced as selected by the following options. The default variant |
| 3737 |
for pdp11\-aout is the \fB\-\-omagic\fR option, whereas for other |
| 3738 |
targets \fB\-\-nmagic\fR is the default. The \fB\-\-imagic\fR option is |
| 3739 |
defined only for the pdp11\-aout target, while the others are described |
| 3740 |
here as they apply to the pdp11\-aout target. |
| 3741 |
.IP \fB\-N\fR 4 |
| 3742 |
.IX Item "-N" |
| 3743 |
.PD 0 |
| 3744 |
.IP \fB\-\-omagic\fR 4 |
| 3745 |
.IX Item "--omagic" |
| 3746 |
.PD |
| 3747 |
Mark the output as \f(CW\*(C`OMAGIC\*(C'\fR (0407) in the \fIa.out\fR header to |
| 3748 |
indicate that the text segment is not to be write-protected and |
| 3749 |
shared. Since the text and data sections are both readable and |
| 3750 |
writable, the data section is allocated immediately contiguous after |
| 3751 |
the text segment. This is the oldest format for PDP11 executable |
| 3752 |
programs and is the default for \fBld\fR on PDP11 Unix systems |
| 3753 |
from the beginning through 2.11BSD. |
| 3754 |
.IP \fB\-n\fR 4 |
| 3755 |
.IX Item "-n" |
| 3756 |
.PD 0 |
| 3757 |
.IP \fB\-\-nmagic\fR 4 |
| 3758 |
.IX Item "--nmagic" |
| 3759 |
.PD |
| 3760 |
Mark the output as \f(CW\*(C`NMAGIC\*(C'\fR (0410) in the \fIa.out\fR header to |
| 3761 |
indicate that when the output file is executed, the text portion will |
| 3762 |
be read-only and shareable among all processes executing the same |
| 3763 |
file. This involves moving the data areas up to the first possible 8K |
| 3764 |
byte page boundary following the end of the text. This option creates |
| 3765 |
a \fIpure executable\fR format. |
| 3766 |
.IP \fB\-z\fR 4 |
| 3767 |
.IX Item "-z" |
| 3768 |
.PD 0 |
| 3769 |
.IP \fB\-\-imagic\fR 4 |
| 3770 |
.IX Item "--imagic" |
| 3771 |
.PD |
| 3772 |
Mark the output as \f(CW\*(C`IMAGIC\*(C'\fR (0411) in the \fIa.out\fR header to |
| 3773 |
indicate that when the output file is executed, the program text and |
| 3774 |
data areas will be loaded into separate address spaces using the split |
| 3775 |
instruction and data space feature of the memory management unit in |
| 3776 |
larger models of the PDP11. This doubles the address space available |
| 3777 |
to the program. The text segment is again pure, write-protected, and |
| 3778 |
shareable. The only difference in the output format between this |
| 3779 |
option and the others, besides the magic number, is that both the text |
| 3780 |
and data sections start at location 0. The \fB\-z\fR option selected |
| 3781 |
this format in 2.11BSD. This option creates a \fIseparate |
| 3782 |
executable\fR format. |
| 3783 |
.IP \fB\-\-no\-omagic\fR 4 |
| 3784 |
.IX Item "--no-omagic" |
| 3785 |
Equivalent to \fB\-\-nmagic\fR for pdp11\-aout. |
| 3786 |
.SH ENVIRONMENT |
| 3787 |
.IX Header "ENVIRONMENT" |
| 3788 |
You can change the behaviour of \fBld\fR with the environment variables |
| 3789 |
\&\f(CW\*(C`GNUTARGET\*(C'\fR, |
| 3790 |
\&\f(CW\*(C`LDEMULATION\*(C'\fR and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR. |
| 3791 |
.PP |
| 3792 |
\&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't |
| 3793 |
use \fB\-b\fR (or its synonym \fB\-\-format\fR). Its value should be one |
| 3794 |
of the BFD names for an input format. If there is no |
| 3795 |
\&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \fBld\fR uses the natural format |
| 3796 |
of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then BFD |
| 3797 |
attempts to discover the input format by examining binary input files; |
| 3798 |
this method often succeeds, but there are potential ambiguities, since |
| 3799 |
there is no method of ensuring that the magic number used to specify |
| 3800 |
object-file formats is unique. However, the configuration procedure for |
| 3801 |
BFD on each system places the conventional format for that system first |
| 3802 |
in the search-list, so ambiguities are resolved in favor of convention. |
| 3803 |
.PP |
| 3804 |
\&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the |
| 3805 |
\&\fB\-m\fR option. The emulation can affect various aspects of linker |
| 3806 |
behaviour, particularly the default linker script. You can list the |
| 3807 |
available emulations with the \fB\-\-verbose\fR or \fB\-V\fR options. If |
| 3808 |
the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment |
| 3809 |
variable is not defined, the default emulation depends upon how the |
| 3810 |
linker was configured. |
| 3811 |
.PP |
| 3812 |
Normally, the linker will default to demangling symbols. However, if |
| 3813 |
\&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will |
| 3814 |
default to not demangling symbols. This environment variable is used in |
| 3815 |
a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program. The default |
| 3816 |
may be overridden by the \fB\-\-demangle\fR and \fB\-\-no\-demangle\fR |
| 3817 |
options. |
| 3818 |
.PP |
| 3819 |
If the PE/COFF specific \fB\-\-insert\-timestamp\fR is active and the |
| 3820 |
\&\fBSOURCE_DATE_EPOCH\fR environment variable is defined, then the |
| 3821 |
timestamp value in this variable will be inserted into the COFF header |
| 3822 |
instead of the current time. |
| 3823 |
.PP |
| 3824 |
If the \f(CW\*(C`LD_STATS\*(C'\fR environment variable is defined then linker |
| 3825 |
resource use information will be recorded, just as if the |
| 3826 |
\&\fB\-\-stats\fR option had been used. If the \f(CW\*(C`LD_STATS\*(C'\fR |
| 3827 |
variable has a string value then this will used as the name of a file |
| 3828 |
into which the information should be stored. Otherwise the information |
| 3829 |
will be sent to the standard output stream. |
| 3830 |
.SH "SEE ALSO" |
| 3831 |
.IX Header "SEE ALSO" |
| 3832 |
\&\fBar\fR\|(1), \fBnm\fR\|(1), \fBobjcopy\fR\|(1), \fBobjdump\fR\|(1), \fBreadelf\fR\|(1) and |
| 3833 |
the Info entries for \fIbinutils\fR and |
| 3834 |
\&\fIld\fR. |
| 3835 |
.SH COPYRIGHT |
| 3836 |
.IX Header "COPYRIGHT" |
| 3837 |
Copyright (c) 1991\-2026 Free Software Foundation, Inc. |
| 3838 |
.PP |
| 3839 |
Permission is granted to copy, distribute and/or modify this document |
| 3840 |
under the terms of the GNU Free Documentation License, Version 1.3 |
| 3841 |
or any later version published by the Free Software Foundation; |
| 3842 |
with no Invariant Sections, with no Front-Cover Texts, and with no |
| 3843 |
Back-Cover Texts. A copy of the license is included in the |
| 3844 |
section entitled "GNU Free Documentation License". |