]>
Commit | Line | Data |
---|---|---|
506eee22 NC |
1 | .\" Automatically generated by Pod::Man version 1.02 |
2 | .\" Tue May 22 15:43:56 2001 | |
3 | .\" | |
4 | .\" Standard preamble: | |
5 | .\" ====================================================================== | |
6 | .de Sh \" Subsection heading | |
252b5132 | 7 | .br |
0285c67d NC |
8 | .if t .Sp |
9 | .ne 5 | |
10 | .PP | |
11 | \fB\\$1\fR | |
12 | .PP | |
13 | .. | |
506eee22 | 14 | .de Sp \" Vertical space (when we can't use .PP) |
0285c67d NC |
15 | .if t .sp .5v |
16 | .if n .sp | |
17 | .. | |
506eee22 | 18 | .de Ip \" List item |
252b5132 | 19 | .br |
0285c67d NC |
20 | .ie \\n(.$>=3 .ne \\$3 |
21 | .el .ne 3 | |
22 | .IP "\\$1" \\$2 | |
23 | .. | |
506eee22 | 24 | .de Vb \" Begin verbatim text |
0285c67d NC |
25 | .ft CW |
26 | .nf | |
27 | .ne \\$1 | |
28 | .. | |
506eee22 | 29 | .de Ve \" End verbatim text |
0285c67d | 30 | .ft R |
252b5132 | 31 | |
0285c67d NC |
32 | .fi |
33 | .. | |
506eee22 NC |
34 | .\" Set up some character translations and predefined strings. \*(-- will |
35 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
36 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
37 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used | |
38 | .\" to do unbreakable dashes and therefore won't be available. \*(C` and | |
39 | .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> | |
0285c67d | 40 | .tr \(*W-|\(bv\*(Tr |
506eee22 | 41 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
0285c67d | 42 | .ie n \{\ |
506eee22 NC |
43 | . ds -- \(*W- |
44 | . ds PI pi | |
45 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
46 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
47 | . ds L" "" | |
48 | . ds R" "" | |
49 | . ds C` ` | |
50 | . ds C' ' | |
0285c67d NC |
51 | 'br\} |
52 | .el\{\ | |
506eee22 NC |
53 | . ds -- \|\(em\| |
54 | . ds PI \(*p | |
55 | . ds L" `` | |
56 | . ds R" '' | |
0285c67d | 57 | 'br\} |
506eee22 NC |
58 | .\" |
59 | .\" If the F register is turned on, we'll generate index entries on stderr | |
60 | .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and | |
61 | .\" index entries marked with X<> in POD. Of course, you'll have to process | |
62 | .\" the output yourself in some meaningful fashion. | |
63 | .if \nF \{\ | |
64 | . de IX | |
65 | . tm Index:\\$1\t\\n%\t"\\$2" | |
66 | . . | |
67 | . nr % 0 | |
68 | . rr F | |
0285c67d | 69 | .\} |
506eee22 NC |
70 | .\" |
71 | .\" For nroff, turn off justification. Always turn off hyphenation; it | |
72 | .\" makes way too many mistakes in technical documents. | |
73 | .hy 0 | |
74 | .\" | |
75 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
76 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
0285c67d | 77 | .bd B 3 |
506eee22 | 78 | . \" fudge factors for nroff and troff |
0285c67d | 79 | .if n \{\ |
506eee22 NC |
80 | . ds #H 0 |
81 | . ds #V .8m | |
82 | . ds #F .3m | |
83 | . ds #[ \f1 | |
84 | . ds #] \fP | |
0285c67d NC |
85 | .\} |
86 | .if t \{\ | |
506eee22 NC |
87 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
88 | . ds #V .6m | |
89 | . ds #F 0 | |
90 | . ds #[ \& | |
91 | . ds #] \& | |
0285c67d | 92 | .\} |
506eee22 | 93 | . \" simple accents for nroff and troff |
0285c67d | 94 | .if n \{\ |
506eee22 NC |
95 | . ds ' \& |
96 | . ds ` \& | |
97 | . ds ^ \& | |
98 | . ds , \& | |
99 | . ds ~ ~ | |
100 | . ds / | |
0285c67d NC |
101 | .\} |
102 | .if t \{\ | |
506eee22 NC |
103 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
104 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
105 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
106 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
107 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
108 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
0285c67d | 109 | .\} |
506eee22 | 110 | . \" troff and (daisy-wheel) nroff accents |
0285c67d NC |
111 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
112 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
0285c67d NC |
113 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
114 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
115 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
116 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
117 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
118 | .ds ae a\h'-(\w'a'u*4/10)'e | |
119 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
506eee22 | 120 | . \" corrections for vroff |
0285c67d NC |
121 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
122 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
506eee22 | 123 | . \" for low resolution devices (crt and lpr) |
0285c67d NC |
124 | .if \n(.H>23 .if \n(.V>19 \ |
125 | \{\ | |
506eee22 NC |
126 | . ds : e |
127 | . ds 8 ss | |
128 | . ds o a | |
129 | . ds d- d\h'-1'\(ga | |
130 | . ds D- D\h'-1'\(hy | |
131 | . ds th \o'bp' | |
132 | . ds Th \o'LP' | |
133 | . ds ae ae | |
134 | . ds Ae AE | |
0285c67d NC |
135 | .\} |
136 | .rm #[ #] #H #V #F C | |
506eee22 NC |
137 | .\" ====================================================================== |
138 | .\" | |
139 | .IX Title "LD 1" | |
140 | .TH LD 1 "binutils-2.11.90" "2001-05-22" "GNU" | |
141 | .UC | |
0285c67d | 142 | .SH "NAME" |
506eee22 | 143 | ld \- Using \s-1LD\s0, the \s-1GNU\s0 linker |
0285c67d | 144 | .SH "SYNOPSIS" |
506eee22 | 145 | .IX Header "SYNOPSIS" |
0285c67d NC |
146 | ld [ options ] objfile... |
147 | .SH "DESCRIPTION" | |
506eee22 NC |
148 | .IX Header "DESCRIPTION" |
149 | \&\f(CW\*(C`ld\*(C'\fR combines a number of object and archive files, relocates | |
0285c67d | 150 | their data and ties up symbol references. Usually the last step in |
506eee22 | 151 | compiling a program is to run \f(CW\*(C`ld\*(C'\fR. |
0285c67d | 152 | .PP |
506eee22 NC |
153 | \&\f(CW\*(C`ld\*(C'\fR accepts Linker Command Language files written in |
154 | a superset of \s-1AT&T\s0's Link Editor Command Language syntax, | |
0285c67d NC |
155 | to provide explicit and total control over the linking process. |
156 | .PP | |
157 | This man page does not describe the command language; see the | |
506eee22 NC |
158 | \&\f(CW\*(C`ld\*(C'\fR entry in \f(CW\*(C`info\*(C'\fR, or the manual |
159 | ld: the \s-1GNU\s0 linker, for full details on the command language and | |
160 | on other aspects of the \s-1GNU\s0 linker. | |
0285c67d | 161 | .PP |
506eee22 NC |
162 | This version of \f(CW\*(C`ld\*(C'\fR uses the general purpose \s-1BFD\s0 libraries |
163 | to operate on object files. This allows \f(CW\*(C`ld\*(C'\fR to read, combine, and | |
164 | write object files in many different formats\-\-\-for example, \s-1COFF\s0 or | |
165 | \&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any | |
0285c67d NC |
166 | available kind of object file. |
167 | .PP | |
506eee22 | 168 | Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other |
252b5132 RH |
169 | linkers in providing diagnostic information. Many linkers abandon |
170 | execution immediately upon encountering an error; whenever possible, | |
506eee22 | 171 | \&\f(CW\*(C`ld\*(C'\fR continues executing, allowing you to identify other errors |
252b5132 | 172 | (or, in some cases, to get an output file in spite of the error). |
0285c67d | 173 | .PP |
506eee22 | 174 | The \s-1GNU\s0 linker \f(CW\*(C`ld\*(C'\fR is meant to cover a broad range of situations, |
252b5132 | 175 | and to be as compatible as possible with other linkers. As a result, |
0285c67d NC |
176 | you have many choices to control its behavior. |
177 | .SH "OPTIONS" | |
506eee22 | 178 | .IX Header "OPTIONS" |
0285c67d NC |
179 | The linker supports a plethora of command-line options, but in actual |
180 | practice few of them are used in any particular context. | |
506eee22 | 181 | For instance, a frequent use of \f(CW\*(C`ld\*(C'\fR is to link standard Unix |
252b5132 | 182 | object files on a standard, supported Unix system. On such a system, to |
506eee22 | 183 | link a file \f(CW\*(C`hello.o\*(C'\fR: |
0285c67d | 184 | .PP |
506eee22 | 185 | .Vb 1 |
0285c67d NC |
186 | \& ld -o I<output> /lib/crt0.o hello.o -lc |
187 | .Ve | |
506eee22 NC |
188 | This tells \f(CW\*(C`ld\*(C'\fR to produce a file called \fIoutput\fR as the |
189 | result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and | |
190 | the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search | |
0285c67d NC |
191 | directories. (See the discussion of the \fB\-l\fR option below.) |
192 | .PP | |
506eee22 | 193 | Some of the command-line options to \f(CW\*(C`ld\*(C'\fR may be specified at any |
0285c67d NC |
194 | point in the command line. However, options which refer to files, such |
195 | as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at | |
196 | which the option appears in the command line, relative to the object | |
197 | files and other file options. Repeating non-file options with a | |
252b5132 | 198 | different argument will either have no further effect, or override prior |
0285c67d NC |
199 | occurrences (those further to the left on the command line) of that |
200 | option. Options which may be meaningfully specified more than once are | |
201 | noted in the descriptions below. | |
202 | .PP | |
203 | Non-option arguments are object files or archives which are to be linked | |
204 | together. They may follow, precede, or be mixed in with command-line | |
205 | options, except that an object file argument may not be placed between | |
206 | an option and its argument. | |
207 | .PP | |
208 | Usually the linker is invoked with at least one object file, but you can | |
209 | specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR, | |
210 | and the script command language. If \fIno\fR binary input files at all | |
211 | are specified, the linker does not produce any output, and issues the | |
212 | message \fBNo input files\fR. | |
213 | .PP | |
214 | If the linker can not recognize the format of an object file, it will | |
215 | assume that it is a linker script. A script specified in this way | |
216 | augments the main linker script used for the link (either the default | |
217 | linker script or the one specified by using \fB\-T\fR). This feature | |
218 | permits the linker to link against a file which appears to be an object | |
219 | or an archive, but actually merely defines some symbol values, or uses | |
506eee22 | 220 | \&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Note that |
0285c67d NC |
221 | specifying a script in this way should only be used to augment the main |
222 | linker script; if you want to use some command that logically can only | |
506eee22 | 223 | appear once, such as the \f(CW\*(C`SECTIONS\*(C'\fR or \f(CW\*(C`MEMORY\*(C'\fR command, you |
0285c67d NC |
224 | must replace the default linker script using the \fB\-T\fR option. |
225 | .PP | |
226 | For options whose names are a single letter, | |
227 | option arguments must either follow the option letter without intervening | |
252b5132 RH |
228 | whitespace, or be given as separate arguments immediately following the |
229 | option that requires them. | |
0285c67d NC |
230 | .PP |
231 | For options whose names are multiple letters, either one dash or two can | |
232 | precede the option name; for example, \fB\-trace-symbol\fR and | |
506eee22 NC |
233 | \&\fB\*(--trace-symbol\fR are equivalent. Note \- there is one exception to |
234 | this rule. Multiple letter options that start with a lower case 'o' can | |
0285c67d | 235 | only be preceeded by two dashes. This is to reduce confusion with the |
506eee22 NC |
236 | \&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file |
237 | name to \fBmagic\fR whereas \fB\*(--omagic\fR sets the \s-1NMAGIC\s0 flag on the | |
0285c67d NC |
238 | output. |
239 | .PP | |
240 | Arguments to multiple-letter options must either be separated from the | |
241 | option name by an equals sign, or be given as separate arguments | |
242 | immediately following the option that requires them. For example, | |
506eee22 | 243 | \&\fB\*(--trace-symbol foo\fR and \fB\*(--trace-symbol=foo\fR are equivalent. |
0285c67d NC |
244 | Unique abbreviations of the names of multiple-letter options are |
245 | accepted. | |
246 | .PP | |
247 | Note \- if the linker is being invoked indirectly, via a compiler driver | |
248 | (eg \fBgcc\fR) then all the linker command line options should be | |
249 | prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular | |
250 | compiler driver) like this: | |
251 | .PP | |
506eee22 | 252 | .Vb 1 |
0285c67d NC |
253 | \& gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup |
254 | .Ve | |
255 | This is important, because otherwise the compiler driver program may | |
256 | silently drop the linker options, resulting in a bad link. | |
257 | .PP | |
506eee22 | 258 | Here is a table of the generic command line switches accepted by the \s-1GNU\s0 |
0285c67d | 259 | linker: |
506eee22 NC |
260 | .Ip "\f(CW\*(C`\-a\f(CIkeyword\f(CW\*(C'\fR" 4 |
261 | .IX Item "-akeyword" | |
0285c67d NC |
262 | This option is supported for \s-1HP/UX\s0 compatibility. The \fIkeyword\fR |
263 | argument must be one of the strings \fBarchive\fR, \fBshared\fR, or | |
506eee22 NC |
264 | \&\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to |
265 | \&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent | |
0285c67d | 266 | to \fB\-Bdynamic\fR. This option may be used any number of times. |
506eee22 NC |
267 | .Ip "\f(CW\*(C`\-A\f(CIarchitecture\f(CW\*(C'\fR" 4 |
268 | .IX Item "-Aarchitecture" | |
269 | .Ip "\f(CW\*(C`\-\-architecture=\f(CIarchitecture\f(CW\*(C'\fR" 4 | |
270 | .IX Item "--architecture=architecture" | |
271 | In the current release of \f(CW\*(C`ld\*(C'\fR, this option is useful only for the | |
272 | Intel 960 family of architectures. In that \f(CW\*(C`ld\*(C'\fR configuration, the | |
273 | \&\fIarchitecture\fR argument identifies the particular architecture in | |
0285c67d NC |
274 | the 960 family, enabling some safeguards and modifying the |
275 | archive-library search path. | |
276 | .Sp | |
506eee22 | 277 | Future releases of \f(CW\*(C`ld\*(C'\fR may support similar functionality for |
252b5132 | 278 | other architecture families. |
506eee22 NC |
279 | .Ip "\f(CW\*(C`\-b \f(CIinput\-format\f(CW\*(C'\fR" 4 |
280 | .IX Item "-b input-format" | |
281 | .Ip "\f(CW\*(C`\-\-format=\f(CIinput\-format\f(CW\*(C'\fR" 4 | |
282 | .IX Item "--format=input-format" | |
283 | \&\f(CW\*(C`ld\*(C'\fR may be configured to support more than one kind of object | |
284 | file. If your \f(CW\*(C`ld\*(C'\fR is configured this way, you can use the | |
285 | \&\fB\-b\fR option to specify the binary format for input object files | |
286 | that follow this option on the command line. Even when \f(CW\*(C`ld\*(C'\fR is | |
0285c67d | 287 | configured to support alternative object formats, you don't usually need |
506eee22 | 288 | to specify this, as \f(CW\*(C`ld\*(C'\fR should be configured to expect as a |
0285c67d | 289 | default input format the most usual format on each machine. |
506eee22 | 290 | \&\fIinput-format\fR is a text string, the name of a particular format |
0285c67d NC |
291 | supported by the \s-1BFD\s0 libraries. (You can list the available binary |
292 | formats with \fBobjdump \-i\fR.) | |
293 | .Sp | |
252b5132 | 294 | You may want to use this option if you are linking files with an unusual |
0285c67d | 295 | binary format. You can also use \fB\-b\fR to switch formats explicitly (when |
252b5132 | 296 | linking object files of different formats), by including |
506eee22 | 297 | \&\fB\-b\fR \fIinput-format\fR before each group of object files in a |
0285c67d NC |
298 | particular format. |
299 | .Sp | |
252b5132 | 300 | The default format is taken from the environment variable |
506eee22 | 301 | \&\f(CW\*(C`GNUTARGET\*(C'\fR. |
0285c67d NC |
302 | .Sp |
303 | You can also define the input format from a script, using the command | |
506eee22 NC |
304 | \&\f(CW\*(C`TARGET\*(C'\fR; |
305 | .Ip "\f(CW\*(C`\-c \f(CIMRI\-commandfile\f(CW\*(C'\fR" 4 | |
306 | .IX Item "-c MRI-commandfile" | |
307 | .Ip "\f(CW\*(C`\-\-mri\-script=\f(CIMRI\-commandfile\f(CW\*(C'\fR" 4 | |
308 | .IX Item "--mri-script=MRI-commandfile" | |
309 | For compatibility with linkers produced by \s-1MRI\s0, \f(CW\*(C`ld\*(C'\fR accepts script | |
0285c67d NC |
310 | files written in an alternate, restricted command language, described in |
311 | the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation. | |
312 | Introduce \s-1MRI\s0 script files with | |
313 | the option \fB\-c\fR; use the \fB\-T\fR option to run linker | |
506eee22 NC |
314 | scripts written in the general-purpose \f(CW\*(C`ld\*(C'\fR scripting language. |
315 | If \fIMRI-cmdfile\fR does not exist, \f(CW\*(C`ld\*(C'\fR looks for it in the directories | |
0285c67d | 316 | specified by any \fB\-L\fR options. |
506eee22 NC |
317 | .Ip "\f(CW\*(C`\-d\*(C'\fR" 4 |
318 | .IX Item "-d" | |
319 | .Ip "\f(CW\*(C`\-dc\*(C'\fR" 4 | |
320 | .IX Item "-dc" | |
321 | .Ip "\f(CW\*(C`\-dp\*(C'\fR" 4 | |
322 | .IX Item "-dp" | |
0285c67d NC |
323 | These three options are equivalent; multiple forms are supported for |
324 | compatibility with other linkers. They assign space to common symbols | |
325 | even if a relocatable output file is specified (with \fB\-r\fR). The | |
506eee22 NC |
326 | script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect. |
327 | .Ip "\f(CW\*(C`\-e \f(CIentry\f(CW\*(C'\fR" 4 | |
328 | .IX Item "-e entry" | |
329 | .Ip "\f(CW\*(C`\-\-entry=\f(CIentry\f(CW\*(C'\fR" 4 | |
330 | .IX Item "--entry=entry" | |
0285c67d NC |
331 | Use \fIentry\fR as the explicit symbol for beginning execution of your |
332 | program, rather than the default entry point. If there is no symbol | |
333 | named \fIentry\fR, the linker will try to parse \fIentry\fR as a number, | |
334 | and use that as the entry address (the number will be interpreted in | |
335 | base 10; you may use a leading \fB0x\fR for base 16, or a leading | |
506eee22 NC |
336 | \&\fB0\fR for base 8). |
337 | .Ip "\f(CW\*(C`\-E\*(C'\fR" 4 | |
338 | .IX Item "-E" | |
339 | .Ip "\f(CW\*(C`\-\-export\-dynamic\*(C'\fR" 4 | |
340 | .IX Item "--export-dynamic" | |
0285c67d NC |
341 | When creating a dynamically linked executable, add all symbols to the |
342 | dynamic symbol table. The dynamic symbol table is the set of symbols | |
343 | which are visible from dynamic objects at run time. | |
344 | .Sp | |
345 | If you do not use this option, the dynamic symbol table will normally | |
346 | contain only those symbols which are referenced by some dynamic object | |
347 | mentioned in the link. | |
348 | .Sp | |
506eee22 | 349 | If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer |
0285c67d NC |
350 | back to the symbols defined by the program, rather than some other |
351 | dynamic object, then you will probably need to use this option when | |
352 | linking the program itself. | |
506eee22 NC |
353 | .Ip "\f(CW\*(C`\-EB\*(C'\fR" 4 |
354 | .IX Item "-EB" | |
0285c67d | 355 | Link big-endian objects. This affects the default output format. |
506eee22 NC |
356 | .Ip "\f(CW\*(C`\-EL\*(C'\fR" 4 |
357 | .IX Item "-EL" | |
0285c67d | 358 | Link little-endian objects. This affects the default output format. |
506eee22 NC |
359 | .Ip "\f(CW\*(C`\-f\*(C'\fR" 4 |
360 | .IX Item "-f" | |
361 | .Ip "\f(CW\*(C`\-\-auxiliary \f(CIname\f(CW\*(C'\fR" 4 | |
362 | .IX Item "--auxiliary name" | |
0285c67d NC |
363 | When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field |
364 | to the specified name. This tells the dynamic linker that the symbol | |
365 | table of the shared object should be used as an auxiliary filter on the | |
366 | symbol table of the shared object \fIname\fR. | |
367 | .Sp | |
368 | If you later link a program against this filter object, then, when you | |
369 | run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field. If | |
370 | the dynamic linker resolves any symbols from the filter object, it will | |
371 | first check whether there is a definition in the shared object | |
506eee22 | 372 | \&\fIname\fR. If there is one, it will be used instead of the definition |
0285c67d NC |
373 | in the filter object. The shared object \fIname\fR need not exist. |
374 | Thus the shared object \fIname\fR may be used to provide an alternative | |
375 | implementation of certain functions, perhaps for debugging or for | |
376 | machine specific performance. | |
377 | .Sp | |
378 | This option may be specified more than once. The \s-1DT_AUXILIARY\s0 entries | |
379 | will be created in the order in which they appear on the command line. | |
506eee22 NC |
380 | .Ip "\f(CW\*(C`\-F \f(CIname\f(CW\*(C'\fR" 4 |
381 | .IX Item "-F name" | |
382 | .Ip "\f(CW\*(C`\-\-filter \f(CIname\f(CW\*(C'\fR" 4 | |
383 | .IX Item "--filter name" | |
0285c67d NC |
384 | When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to |
385 | the specified name. This tells the dynamic linker that the symbol table | |
386 | of the shared object which is being created should be used as a filter | |
387 | on the symbol table of the shared object \fIname\fR. | |
388 | .Sp | |
389 | If you later link a program against this filter object, then, when you | |
390 | run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field. The | |
391 | dynamic linker will resolve symbols according to the symbol table of the | |
392 | filter object as usual, but it will actually link to the definitions | |
393 | found in the shared object \fIname\fR. Thus the filter object can be | |
394 | used to select a subset of the symbols provided by the object | |
506eee22 | 395 | \&\fIname\fR. |
0285c67d | 396 | .Sp |
506eee22 | 397 | Some older linkers used the \f(CW\*(C`\-F\*(C'\fR option throughout a compilation |
0285c67d NC |
398 | toolchain for specifying object-file format for both input and output |
399 | object files. The \s-1GNU\s0 linker uses other mechanisms for this | |
506eee22 NC |
400 | purpose: the \f(CW\*(C`\-b\*(C'\fR, \f(CW\*(C`\-\-format\*(C'\fR, \f(CW\*(C`\-\-oformat\*(C'\fR options, the |
401 | \&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR | |
402 | environment variable. The \s-1GNU\s0 linker will ignore the \f(CW\*(C`\-F\*(C'\fR | |
0285c67d | 403 | option when not creating an \s-1ELF\s0 shared object. |
506eee22 NC |
404 | .Ip "\f(CW\*(C`\-fini \f(CIname\f(CW\*(C'\fR" 4 |
405 | .IX Item "-fini name" | |
0285c67d NC |
406 | When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the |
407 | executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the | |
506eee22 | 408 | address of the function. By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as |
0285c67d | 409 | the function to call. |
506eee22 NC |
410 | .Ip "\f(CW\*(C`\-g\*(C'\fR" 4 |
411 | .IX Item "-g" | |
0285c67d | 412 | Ignored. Provided for compatibility with other tools. |
506eee22 NC |
413 | .Ip "\f(CW\*(C`\-G\f(CIvalue\f(CW\*(C'\fR" 4 |
414 | .IX Item "-Gvalue" | |
415 | .Ip "\f(CW\*(C`\-\-gpsize=\f(CIvalue\f(CW\*(C'\fR" 4 | |
416 | .IX Item "--gpsize=value" | |
0285c67d | 417 | Set the maximum size of objects to be optimized using the \s-1GP\s0 register to |
506eee22 NC |
418 | \&\fIsize\fR. This is only meaningful for object file formats such as |
419 | \&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different | |
0285c67d | 420 | sections. This is ignored for other object file formats. |
506eee22 NC |
421 | .Ip "\f(CW\*(C`\-h\f(CIname\f(CW\*(C'\fR" 4 |
422 | .IX Item "-hname" | |
423 | .Ip "\f(CW\*(C`\-soname=\f(CIname\f(CW\*(C'\fR" 4 | |
424 | .IX Item "-soname=name" | |
0285c67d NC |
425 | When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to |
426 | the specified name. When an executable is linked with a shared object | |
427 | which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic | |
428 | linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0 | |
429 | field rather than the using the file name given to the linker. | |
506eee22 NC |
430 | .Ip "\f(CW\*(C`\-i\*(C'\fR" 4 |
431 | .IX Item "-i" | |
0285c67d | 432 | Perform an incremental link (same as option \fB\-r\fR). |
506eee22 NC |
433 | .Ip "\f(CW\*(C`\-init \f(CIname\f(CW\*(C'\fR" 4 |
434 | .IX Item "-init name" | |
0285c67d NC |
435 | When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the |
436 | executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address | |
506eee22 | 437 | of the function. By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the |
0285c67d | 438 | function to call. |
506eee22 NC |
439 | .Ip "\f(CW\*(C`\-l\f(CIarchive\f(CW\*(C'\fR" 4 |
440 | .IX Item "-larchive" | |
441 | .Ip "\f(CW\*(C`\-\-library=\f(CIarchive\f(CW\*(C'\fR" 4 | |
442 | .IX Item "--library=archive" | |
0285c67d | 443 | Add archive file \fIarchive\fR to the list of files to link. This |
506eee22 NC |
444 | option may be used any number of times. \f(CW\*(C`ld\*(C'\fR will search its |
445 | path-list for occurrences of \f(CW\*(C`lib\f(CIarchive\f(CW.a\*(C'\fR for every | |
446 | \&\fIarchive\fR specified. | |
0285c67d | 447 | .Sp |
506eee22 NC |
448 | On systems which support shared libraries, \f(CW\*(C`ld\*(C'\fR may also search for |
449 | libraries with extensions other than \f(CW\*(C`.a\*(C'\fR. Specifically, on \s-1ELF\s0 | |
450 | and SunOS systems, \f(CW\*(C`ld\*(C'\fR will search a directory for a library with | |
451 | an extension of \f(CW\*(C`.so\*(C'\fR before searching for one with an extension of | |
452 | \&\f(CW\*(C`.a\*(C'\fR. By convention, a \f(CW\*(C`.so\*(C'\fR extension indicates a shared | |
0285c67d NC |
453 | library. |
454 | .Sp | |
455 | The linker will search an archive only once, at the location where it is | |
456 | specified on the command line. If the archive defines a symbol which | |
457 | was undefined in some object which appeared before the archive on the | |
458 | command line, the linker will include the appropriate \fIfile\fR\|(s) from the | |
459 | archive. However, an undefined symbol in an object appearing later on | |
460 | the command line will not cause the linker to search the archive again. | |
461 | .Sp | |
506eee22 | 462 | See the \f(CW\*(C`\-(\*(C'\fR option for a way to force the linker to search |
0285c67d NC |
463 | archives multiple times. |
464 | .Sp | |
465 | You may list the same archive multiple times on the command line. | |
466 | .Sp | |
467 | This type of archive searching is standard for Unix linkers. However, | |
506eee22 | 468 | if you are using \f(CW\*(C`ld\*(C'\fR on \s-1AIX\s0, note that it is different from the |
0285c67d | 469 | behaviour of the \s-1AIX\s0 linker. |
506eee22 NC |
470 | .Ip "\f(CW\*(C`\-L\f(CIsearchdir\f(CW\*(C'\fR" 4 |
471 | .IX Item "-Lsearchdir" | |
472 | .Ip "\f(CW\*(C`\-\-library\-path=\f(CIsearchdir\f(CW\*(C'\fR" 4 | |
473 | .IX Item "--library-path=searchdir" | |
474 | Add path \fIsearchdir\fR to the list of paths that \f(CW\*(C`ld\*(C'\fR will search | |
475 | for archive libraries and \f(CW\*(C`ld\*(C'\fR control scripts. You may use this | |
0285c67d NC |
476 | option any number of times. The directories are searched in the order |
477 | in which they are specified on the command line. Directories specified | |
478 | on the command line are searched before the default directories. All | |
506eee22 | 479 | \&\f(CW\*(C`\-L\*(C'\fR options apply to all \f(CW\*(C`\-l\*(C'\fR options, regardless of the |
0285c67d NC |
480 | order in which the options appear. |
481 | .Sp | |
482 | The default set of paths searched (without being specified with | |
506eee22 | 483 | \&\fB\-L\fR) depends on which emulation mode \f(CW\*(C`ld\*(C'\fR is using, and in |
0285c67d NC |
484 | some cases also on how it was configured. |
485 | .Sp | |
486 | The paths can also be specified in a link script with the | |
506eee22 | 487 | \&\f(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched |
0285c67d | 488 | at the point in which the linker script appears in the command line. |
506eee22 NC |
489 | .Ip "\f(CW\*(C`\-m\f(CIemulation\f(CW\*(C'\fR" 4 |
490 | .IX Item "-memulation" | |
0285c67d | 491 | Emulate the \fIemulation\fR linker. You can list the available |
506eee22 | 492 | emulations with the \fB\*(--verbose\fR or \fB\-V\fR options. |
0285c67d NC |
493 | .Sp |
494 | If the \fB\-m\fR option is not used, the emulation is taken from the | |
506eee22 | 495 | \&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined. |
0285c67d NC |
496 | .Sp |
497 | Otherwise, the default emulation depends upon how the linker was | |
498 | configured. | |
506eee22 NC |
499 | .Ip "\f(CW\*(C`\-M\*(C'\fR" 4 |
500 | .IX Item "-M" | |
501 | .Ip "\f(CW\*(C`\-\-print\-map\*(C'\fR" 4 | |
502 | .IX Item "--print-map" | |
0285c67d NC |
503 | Print a link map to the standard output. A link map provides |
504 | information about the link, including the following: | |
506eee22 NC |
505 | .RS 4 |
506 | .Ip "\(bu" 4 | |
0285c67d | 507 | Where object files and symbols are mapped into memory. |
506eee22 | 508 | .Ip "\(bu" 4 |
0285c67d | 509 | How common symbols are allocated. |
506eee22 | 510 | .Ip "\(bu" 4 |
0285c67d NC |
511 | All archive members included in the link, with a mention of the symbol |
512 | which caused the archive member to be brought in. | |
506eee22 NC |
513 | .RE |
514 | .RS 4 | |
515 | .RE | |
516 | .Ip "\f(CW\*(C`\-n\*(C'\fR" 4 | |
517 | .IX Item "-n" | |
518 | .Ip "\f(CW\*(C`\-\-nmagic\*(C'\fR" 4 | |
519 | .IX Item "--nmagic" | |
0285c67d | 520 | Turn off page alignment of sections, and mark the output as |
506eee22 NC |
521 | \&\f(CW\*(C`NMAGIC\*(C'\fR if possible. |
522 | .Ip "\f(CW\*(C`\-N\*(C'\fR" 4 | |
523 | .IX Item "-N" | |
524 | .Ip "\f(CW\*(C`\-\-omagic\*(C'\fR" 4 | |
525 | .IX Item "--omagic" | |
0285c67d NC |
526 | Set the text and data sections to be readable and writable. Also, do |
527 | not page-align the data segment. If the output format supports Unix | |
506eee22 NC |
528 | style magic numbers, mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. |
529 | .Ip "\f(CW\*(C`\-o \f(CIoutput\f(CW\*(C'\fR" 4 | |
530 | .IX Item "-o output" | |
531 | .Ip "\f(CW\*(C`\-\-output=\f(CIoutput\f(CW\*(C'\fR" 4 | |
532 | .IX Item "--output=output" | |
533 | Use \fIoutput\fR as the name for the program produced by \f(CW\*(C`ld\*(C'\fR; if this | |
0285c67d | 534 | option is not specified, the name \fIa.out\fR is used by default. The |
506eee22 NC |
535 | script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name. |
536 | .Ip "\f(CW\*(C`\-O \f(CIlevel\f(CW\*(C'\fR" 4 | |
537 | .IX Item "-O level" | |
538 | If \fIlevel\fR is a numeric values greater than zero \f(CW\*(C`ld\*(C'\fR optimizes | |
0285c67d NC |
539 | the output. This might take significantly longer and therefore probably |
540 | should only be enabled for the final binary. | |
506eee22 NC |
541 | .Ip "\f(CW\*(C`\-q\*(C'\fR" 4 |
542 | .IX Item "-q" | |
543 | .Ip "\f(CW\*(C`\-\-emit\-relocs\*(C'\fR" 4 | |
544 | .IX Item "--emit-relocs" | |
0285c67d NC |
545 | Leave relocation sections and contents in fully linked exececutables. |
546 | Post link analysis and optimization tools may need this information in | |
547 | order to perform correct modifications of executables. This results | |
548 | in larger executables. | |
506eee22 NC |
549 | .Ip "\f(CW\*(C`\-r\*(C'\fR" 4 |
550 | .IX Item "-r" | |
551 | .Ip "\f(CW\*(C`\-\-relocateable\*(C'\fR" 4 | |
552 | .IX Item "--relocateable" | |
553 | Generate relocatable output\-\-\-i.e., generate an output file that can in | |
554 | turn serve as input to \f(CW\*(C`ld\*(C'\fR. This is often called \fIpartial | |
0285c67d NC |
555 | linking\fR. As a side effect, in environments that support standard Unix |
556 | magic numbers, this option also sets the output file's magic number to | |
506eee22 | 557 | \&\f(CW\*(C`OMAGIC\*(C'\fR. |
0285c67d NC |
558 | If this option is not specified, an absolute file is produced. When |
559 | linking \*(C+ programs, this option \fIwill not\fR resolve references to | |
560 | constructors; to do that, use \fB\-Ur\fR. | |
561 | .Sp | |
562 | This option does the same thing as \fB\-i\fR. | |
506eee22 NC |
563 | .Ip "\f(CW\*(C`\-R \f(CIfilename\f(CW\*(C'\fR" 4 |
564 | .IX Item "-R filename" | |
565 | .Ip "\f(CW\*(C`\-\-just\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4 | |
566 | .IX Item "--just-symbols=filename" | |
0285c67d NC |
567 | Read symbol names and their addresses from \fIfilename\fR, but do not |
568 | relocate it or include it in the output. This allows your output file | |
569 | to refer symbolically to absolute locations of memory defined in other | |
570 | programs. You may use this option more than once. | |
571 | .Sp | |
506eee22 | 572 | For compatibility with other \s-1ELF\s0 linkers, if the \f(CW\*(C`\-R\*(C'\fR option is |
0285c67d | 573 | followed by a directory name, rather than a file name, it is treated as |
506eee22 NC |
574 | the \f(CW\*(C`\-rpath\*(C'\fR option. |
575 | .Ip "\f(CW\*(C`\-s\*(C'\fR" 4 | |
576 | .IX Item "-s" | |
577 | .Ip "\f(CW\*(C`\-\-strip\-all\*(C'\fR" 4 | |
578 | .IX Item "--strip-all" | |
0285c67d | 579 | Omit all symbol information from the output file. |
506eee22 NC |
580 | .Ip "\f(CW\*(C`\-S\*(C'\fR" 4 |
581 | .IX Item "-S" | |
582 | .Ip "\f(CW\*(C`\-\-strip\-debug\*(C'\fR" 4 | |
583 | .IX Item "--strip-debug" | |
0285c67d | 584 | Omit debugger symbol information (but not all symbols) from the output file. |
506eee22 NC |
585 | .Ip "\f(CW\*(C`\-t\*(C'\fR" 4 |
586 | .IX Item "-t" | |
587 | .Ip "\f(CW\*(C`\-\-trace\*(C'\fR" 4 | |
588 | .IX Item "--trace" | |
589 | Print the names of the input files as \f(CW\*(C`ld\*(C'\fR processes them. | |
590 | .Ip "\f(CW\*(C`\-T \f(CIscriptfile\f(CW\*(C'\fR" 4 | |
591 | .IX Item "-T scriptfile" | |
592 | .Ip "\f(CW\*(C`\-\-script=\f(CIscriptfile\f(CW\*(C'\fR" 4 | |
593 | .IX Item "--script=scriptfile" | |
0285c67d | 594 | Use \fIscriptfile\fR as the linker script. This script replaces |
506eee22 NC |
595 | \&\f(CW\*(C`ld\*(C'\fR's default linker script (rather than adding to it), so |
596 | \&\fIcommandfile\fR must specify everything necessary to describe the | |
0285c67d NC |
597 | output file. You must use this option if you want to use a command |
598 | which can only appear once in a linker script, such as the | |
506eee22 NC |
599 | \&\f(CW\*(C`SECTIONS\*(C'\fR or \f(CW\*(C`MEMORY\*(C'\fR command. If |
600 | \&\fIscriptfile\fR does not exist in the current directory, \f(CW\*(C`ld\*(C'\fR | |
0285c67d NC |
601 | looks for it in the directories specified by any preceding \fB\-L\fR |
602 | options. Multiple \fB\-T\fR options accumulate. | |
506eee22 NC |
603 | .Ip "\f(CW\*(C`\-u \f(CIsymbol\f(CW\*(C'\fR" 4 |
604 | .IX Item "-u symbol" | |
605 | .Ip "\f(CW\*(C`\-\-undefined=\f(CIsymbol\f(CW\*(C'\fR" 4 | |
606 | .IX Item "--undefined=symbol" | |
0285c67d NC |
607 | Force \fIsymbol\fR to be entered in the output file as an undefined |
608 | symbol. Doing this may, for example, trigger linking of additional | |
609 | modules from standard libraries. \fB\-u\fR may be repeated with | |
610 | different option arguments to enter additional undefined symbols. This | |
506eee22 NC |
611 | option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command. |
612 | .Ip "\f(CW\*(C`\-Ur\*(C'\fR" 4 | |
613 | .IX Item "-Ur" | |
0285c67d | 614 | For anything other than \*(C+ programs, this option is equivalent to |
506eee22 NC |
615 | \&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in |
616 | turn serve as input to \f(CW\*(C`ld\*(C'\fR. When linking \*(C+ programs, \fB\-Ur\fR | |
617 | \&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR. | |
0285c67d NC |
618 | It does not work to use \fB\-Ur\fR on files that were themselves linked |
619 | with \fB\-Ur\fR; once the constructor table has been built, it cannot | |
620 | be added to. Use \fB\-Ur\fR only for the last partial link, and | |
506eee22 NC |
621 | \&\fB\-r\fR for the others. |
622 | .Ip "\f(CW\*(C`\-\-unique[=\f(CI\s\-1SECTION\s0\f(CW]\*(C'\fR" 4 | |
623 | .IX Item "--unique[=SECTION]" | |
0285c67d | 624 | Creates a separate output section for every input section matching |
506eee22 | 625 | \&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is |
0285c67d NC |
626 | missing, for every orphan input section. An orphan section is one not |
627 | specifically mentioned in a linker script. You may use this option | |
628 | multiple times on the command line; It prevents the normal merging of | |
629 | input sections with the same name, overriding output section assignments | |
630 | in a linker script. | |
506eee22 NC |
631 | .Ip "\f(CW\*(C`\-v\*(C'\fR" 4 |
632 | .IX Item "-v" | |
633 | .Ip "\f(CW\*(C`\-\-version\*(C'\fR" 4 | |
634 | .IX Item "--version" | |
635 | .Ip "\f(CW\*(C`\-V\*(C'\fR" 4 | |
636 | .IX Item "-V" | |
637 | Display the version number for \f(CW\*(C`ld\*(C'\fR. The \f(CW\*(C`\-V\*(C'\fR option also | |
0285c67d | 638 | lists the supported emulations. |
506eee22 NC |
639 | .Ip "\f(CW\*(C`\-x\*(C'\fR" 4 |
640 | .IX Item "-x" | |
641 | .Ip "\f(CW\*(C`\-\-discard\-all\*(C'\fR" 4 | |
642 | .IX Item "--discard-all" | |
0285c67d | 643 | Delete all local symbols. |
506eee22 NC |
644 | .Ip "\f(CW\*(C`\-X\*(C'\fR" 4 |
645 | .IX Item "-X" | |
646 | .Ip "\f(CW\*(C`\-\-discard\-locals\*(C'\fR" 4 | |
647 | .IX Item "--discard-locals" | |
0285c67d NC |
648 | Delete all temporary local symbols. For most targets, this is all local |
649 | symbols whose names begin with \fBL\fR. | |
506eee22 NC |
650 | .Ip "\f(CW\*(C`\-y \f(CIsymbol\f(CW\*(C'\fR" 4 |
651 | .IX Item "-y symbol" | |
652 | .Ip "\f(CW\*(C`\-\-trace\-symbol=\f(CIsymbol\f(CW\*(C'\fR" 4 | |
653 | .IX Item "--trace-symbol=symbol" | |
0285c67d NC |
654 | Print the name of each linked file in which \fIsymbol\fR appears. This |
655 | option may be given any number of times. On many systems it is necessary | |
656 | to prepend an underscore. | |
657 | .Sp | |
658 | This option is useful when you have an undefined symbol in your link but | |
659 | don't know where the reference is coming from. | |
506eee22 NC |
660 | .Ip "\f(CW\*(C`\-Y \f(CIpath\f(CW\*(C'\fR" 4 |
661 | .IX Item "-Y path" | |
0285c67d NC |
662 | Add \fIpath\fR to the default library search path. This option exists |
663 | for Solaris compatibility. | |
506eee22 NC |
664 | .Ip "\f(CW\*(C`\-z \f(CIkeyword\f(CW\*(C'\fR" 4 |
665 | .IX Item "-z keyword" | |
666 | The recognized keywords are \f(CW\*(C`initfirst\*(C'\fR, \f(CW\*(C`interpose\*(C'\fR, | |
667 | \&\f(CW\*(C`loadfltr\*(C'\fR, \f(CW\*(C`nodefaultlib\*(C'\fR, \f(CW\*(C`nodelete\*(C'\fR, \f(CW\*(C`nodlopen\*(C'\fR, | |
668 | \&\f(CW\*(C`nodump\*(C'\fR, \f(CW\*(C`now\*(C'\fR and \f(CW\*(C`origin\*(C'\fR. The other keywords are | |
669 | ignored for Solaris compatibility. \f(CW\*(C`initfirst\*(C'\fR marks the object | |
0285c67d | 670 | to be initialized first at runtime before any other objects. |
506eee22 NC |
671 | \&\f(CW\*(C`interpose\*(C'\fR marks the object that its symbol table interposes |
672 | before all symbols but the primary executable. \f(CW\*(C`loadfltr\*(C'\fR marks | |
0285c67d | 673 | the object that its filtees be processed immediately at runtime. |
506eee22 | 674 | \&\f(CW\*(C`nodefaultlib\*(C'\fR marks the object that the search for dependencies |
0285c67d | 675 | of this object will ignore any default library search paths. |
506eee22 NC |
676 | \&\f(CW\*(C`nodelete\*(C'\fR marks the object shouldn't be unloaded at runtime. |
677 | \&\f(CW\*(C`nodlopen\*(C'\fR marks the object not available to \f(CW\*(C`dlopen\*(C'\fR. | |
678 | \&\f(CW\*(C`nodump\*(C'\fR marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. | |
679 | \&\f(CW\*(C`now\*(C'\fR marks the object with the non-lazy runtime binding. | |
680 | \&\f(CW\*(C`origin\*(C'\fR marks the object may contain \f(CW$ORIGIN\fR. | |
681 | \&\f(CW\*(C`defs\*(C'\fR disallows undefined symbols. | |
682 | .Ip "\f(CW\*(C`\-( \f(CIarchives\f(CW \-)\*(C'\fR" 4 | |
683 | .IX Item "-( archives -)" | |
684 | .Ip "\f(CW\*(C`\-\-start\-group \f(CIarchives\f(CW \-\-end\-group\*(C'\fR" 4 | |
685 | .IX Item "--start-group archives --end-group" | |
0285c67d NC |
686 | The \fIarchives\fR should be a list of archive files. They may be |
687 | either explicit file names, or \fB\-l\fR options. | |
688 | .Sp | |
689 | The specified archives are searched repeatedly until no new undefined | |
690 | references are created. Normally, an archive is searched only once in | |
691 | the order that it is specified on the command line. If a symbol in that | |
692 | archive is needed to resolve an undefined symbol referred to by an | |
693 | object in an archive that appears later on the command line, the linker | |
694 | would not be able to resolve that reference. By grouping the archives, | |
695 | they all be searched repeatedly until all possible references are | |
696 | resolved. | |
697 | .Sp | |
698 | Using this option has a significant performance cost. It is best to use | |
699 | it only when there are unavoidable circular references between two or | |
700 | more archives. | |
506eee22 NC |
701 | .Ip "\f(CW\*(C`\-assert \f(CIkeyword\f(CW\*(C'\fR" 4 |
702 | .IX Item "-assert keyword" | |
0285c67d | 703 | This option is ignored for SunOS compatibility. |
506eee22 NC |
704 | .Ip "\f(CW\*(C`\-Bdynamic\*(C'\fR" 4 |
705 | .IX Item "-Bdynamic" | |
706 | .Ip "\f(CW\*(C`\-dy\*(C'\fR" 4 | |
707 | .IX Item "-dy" | |
708 | .Ip "\f(CW\*(C`\-call_shared\*(C'\fR" 4 | |
709 | .IX Item "-call_shared" | |
252b5132 RH |
710 | Link against dynamic libraries. This is only meaningful on platforms |
711 | for which shared libraries are supported. This option is normally the | |
0285c67d NC |
712 | default on such platforms. The different variants of this option are |
713 | for compatibility with various systems. You may use this option | |
714 | multiple times on the command line: it affects library searching for | |
506eee22 NC |
715 | \&\f(CW\*(C`\-l\*(C'\fR options which follow it. |
716 | .Ip "\f(CW\*(C`\-Bgroup\*(C'\fR" 4 | |
717 | .IX Item "-Bgroup" | |
718 | 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 | |
0285c67d NC |
719 | section. This causes the runtime linker to handle lookups in this |
720 | object and its dependencies to be performed only inside the group. | |
506eee22 | 721 | \&\f(CW\*(C`\-\-no\-undefined\*(C'\fR is implied. This option is only meaningful on \s-1ELF\s0 |
0285c67d | 722 | platforms which support shared libraries. |
506eee22 NC |
723 | .Ip "\f(CW\*(C`\-Bstatic\*(C'\fR" 4 |
724 | .IX Item "-Bstatic" | |
725 | .Ip "\f(CW\*(C`\-dn\*(C'\fR" 4 | |
726 | .IX Item "-dn" | |
727 | .Ip "\f(CW\*(C`\-non_shared\*(C'\fR" 4 | |
728 | .IX Item "-non_shared" | |
729 | .Ip "\f(CW\*(C`\-static\*(C'\fR" 4 | |
730 | .IX Item "-static" | |
0285c67d NC |
731 | Do not link against shared libraries. This is only meaningful on |
732 | platforms for which shared libraries are supported. The different | |
733 | variants of this option are for compatibility with various systems. You | |
734 | may use this option multiple times on the command line: it affects | |
506eee22 NC |
735 | library searching for \f(CW\*(C`\-l\*(C'\fR options which follow it. |
736 | .Ip "\f(CW\*(C`\-Bsymbolic\*(C'\fR" 4 | |
737 | .IX Item "-Bsymbolic" | |
0285c67d NC |
738 | When creating a shared library, bind references to global symbols to the |
739 | definition within the shared library, if any. Normally, it is possible | |
740 | for a program linked against a shared library to override the definition | |
741 | within the shared library. This option is only meaningful on \s-1ELF\s0 | |
742 | platforms which support shared libraries. | |
506eee22 NC |
743 | .Ip "\f(CW\*(C`\-\-check\-sections\*(C'\fR" 4 |
744 | .IX Item "--check-sections" | |
745 | .Ip "\f(CW\*(C`\-\-no\-check\-sections\*(C'\fR" 4 | |
746 | .IX Item "--no-check-sections" | |
0285c67d NC |
747 | Asks the linker \fInot\fR to check section addresses after they have |
748 | been assigned to see if there any overlaps. Normally the linker will | |
749 | perform this check, and if it finds any overlaps it will produce | |
750 | suitable error messages. The linker does know about, and does make | |
751 | allowances for sections in overlays. The default behaviour can be | |
506eee22 NC |
752 | restored by using the command line switch \fB\*(--check-sections\fR. |
753 | .Ip "\f(CW\*(C`\-\-cref\*(C'\fR" 4 | |
754 | .IX Item "--cref" | |
252b5132 RH |
755 | Output a cross reference table. If a linker map file is being |
756 | generated, the cross reference table is printed to the map file. | |
757 | Otherwise, it is printed on the standard output. | |
0285c67d NC |
758 | .Sp |
759 | The format of the table is intentionally simple, so that it may be | |
760 | easily processed by a script if necessary. The symbols are printed out, | |
761 | sorted by name. For each symbol, a list of file names is given. If the | |
762 | symbol is defined, the first file listed is the location of the | |
763 | definition. The remaining files contain references to the symbol. | |
506eee22 NC |
764 | .Ip "\f(CW\*(C`\-\-defsym \f(CIsymbol\f(CW=\f(CIexpression\f(CW\*(C'\fR" 4 |
765 | .IX Item "--defsym symbol=expression" | |
252b5132 | 766 | Create a global symbol in the output file, containing the absolute |
0285c67d | 767 | address given by \fIexpression\fR. You may use this option as many |
252b5132 | 768 | times as necessary to define multiple symbols in the command line. A |
0285c67d | 769 | limited form of arithmetic is supported for the \fIexpression\fR in this |
252b5132 | 770 | context: you may give a hexadecimal constant or the name of an existing |
506eee22 | 771 | symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal |
252b5132 | 772 | constants or symbols. If you need more elaborate expressions, consider |
0285c67d NC |
773 | using the linker command language from a script. \fINote:\fR there should be no white |
774 | space between \fIsymbol\fR, the equals sign (``\fB=\fR''), and | |
506eee22 NC |
775 | \&\fIexpression\fR. |
776 | .Ip "\f(CW\*(C`\-\-demangle[=\f(CIstyle\f(CW]\*(C'\fR" 4 | |
777 | .IX Item "--demangle[=style]" | |
778 | .Ip "\f(CW\*(C`\-\-no\-demangle\*(C'\fR" 4 | |
779 | .IX Item "--no-demangle" | |
0285c67d NC |
780 | These options control whether to demangle symbol names in error messages |
781 | and other output. When the linker is told to demangle, it tries to | |
782 | present symbol names in a readable fashion: it strips leading | |
783 | underscores if they are used by the object file format, and converts \*(C+ | |
784 | mangled symbol names into user readable names. Different compilers have | |
785 | different mangling styles. The optional demangling style argument can be used | |
786 | to choose an appropriate demangling style for your compiler. The linker will | |
787 | demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR | |
252b5132 | 788 | is set. These options may be used to override the default. |
506eee22 NC |
789 | .Ip "\f(CW\*(C`\-\-dynamic\-linker \f(CIfile\f(CW\*(C'\fR" 4 |
790 | .IX Item "--dynamic-linker file" | |
0285c67d NC |
791 | Set the name of the dynamic linker. This is only meaningful when |
792 | generating dynamically linked \s-1ELF\s0 executables. The default dynamic | |
793 | linker is normally correct; don't use this unless you know what you are | |
794 | doing. | |
506eee22 NC |
795 | .Ip "\f(CW\*(C`\-\-embedded\-relocs\*(C'\fR" 4 |
796 | .IX Item "--embedded-relocs" | |
0285c67d NC |
797 | This option is only meaningful when linking \s-1MIPS\s0 embedded \s-1PIC\s0 code, |
798 | generated by the \-membedded-pic option to the \s-1GNU\s0 compiler and | |
799 | assembler. It causes the linker to create a table which may be used at | |
800 | runtime to relocate any data which was statically initialized to pointer | |
801 | values. See the code in testsuite/ld-empic for details. | |
506eee22 NC |
802 | .Ip "\f(CW\*(C`\-\-fatal\-warnings\*(C'\fR" 4 |
803 | .IX Item "--fatal-warnings" | |
7ce691ae | 804 | Treat all warnings as errors. |
506eee22 NC |
805 | .Ip "\f(CW\*(C`\-\-force\-exe\-suffix\*(C'\fR" 4 |
806 | .IX Item "--force-exe-suffix" | |
0285c67d NC |
807 | Make sure that an output file has a .exe suffix. |
808 | .Sp | |
809 | If a successfully built fully linked output file does not have a | |
506eee22 NC |
810 | \&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy |
811 | the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This | |
0285c67d NC |
812 | option is useful when using unmodified Unix makefiles on a Microsoft |
813 | Windows host, since some versions of Windows won't run an image unless | |
506eee22 NC |
814 | it ends in a \f(CW\*(C`.exe\*(C'\fR suffix. |
815 | .Ip "\f(CW\*(C`\-\-no\-gc\-sections\*(C'\fR" 4 | |
816 | .IX Item "--no-gc-sections" | |
817 | .Ip "\f(CW\*(C`\-\-gc\-sections\*(C'\fR" 4 | |
818 | .IX Item "--gc-sections" | |
0285c67d NC |
819 | Enable garbage collection of unused input sections. It is ignored on |
820 | targets that do not support this option. This option is not compatible | |
821 | with \fB\-r\fR, nor should it be used with dynamic linking. The default | |
822 | behaviour (of not performing this garbage collection) can be restored by | |
506eee22 NC |
823 | specifying \fB\*(--no-gc-sections\fR on the command line. |
824 | .Ip "\f(CW\*(C`\-\-help\*(C'\fR" 4 | |
825 | .IX Item "--help" | |
252b5132 | 826 | Print a summary of the command-line options on the standard output and exit. |
506eee22 NC |
827 | .Ip "\f(CW\*(C`\-\-target\-help\*(C'\fR" 4 |
828 | .IX Item "--target-help" | |
0285c67d | 829 | Print a summary of all target specific options on the standard output and exit. |
506eee22 NC |
830 | .Ip "\f(CW\*(C`\-Map \f(CImapfile\f(CW\*(C'\fR" 4 |
831 | .IX Item "-Map mapfile" | |
0285c67d | 832 | Print a link map to the file \fImapfile\fR. See the description of the |
506eee22 NC |
833 | \&\fB\-M\fR option, above. |
834 | .Ip "\f(CW\*(C`\-\-no\-keep\-memory\*(C'\fR" 4 | |
835 | .IX Item "--no-keep-memory" | |
836 | \&\f(CW\*(C`ld\*(C'\fR normally optimizes for speed over memory usage by caching the | |
837 | symbol tables of input files in memory. This option tells \f(CW\*(C`ld\*(C'\fR to | |
0285c67d | 838 | instead optimize for memory usage, by rereading the symbol tables as |
506eee22 | 839 | necessary. This may be required if \f(CW\*(C`ld\*(C'\fR runs out of memory space |
0285c67d | 840 | while linking a large executable. |
506eee22 NC |
841 | .Ip "\f(CW\*(C`\-\-no\-undefined\*(C'\fR" 4 |
842 | .IX Item "--no-undefined" | |
843 | .Ip "\f(CW\*(C`\-z defs\*(C'\fR" 4 | |
844 | .IX Item "-z defs" | |
0285c67d NC |
845 | Normally when creating a non-symbolic shared library, undefined symbols |
846 | are allowed and left to be resolved by the runtime loader. These options | |
847 | disallows such undefined symbols. | |
506eee22 NC |
848 | .Ip "\f(CW\*(C`\-\-allow\-shlib\-undefined\*(C'\fR" 4 |
849 | .IX Item "--allow-shlib-undefined" | |
850 | Allow undefined symbols in shared objects even when \-\-no-undefined is | |
0285c67d NC |
851 | set. The net result will be that undefined symbols in regular objects |
852 | will still trigger an error, but undefined symbols in shared objects | |
853 | will be ignored. The implementation of no_undefined makes the | |
854 | assumption that the runtime linker will choke on undefined symbols. | |
855 | However there is at least one system (BeOS) where undefined symbols in | |
856 | shared libraries is normal since the kernel patches them at load time to | |
857 | select which function is most appropriate for the current architecture. | |
858 | I.E. dynamically select an appropriate memset function. Apparently it | |
859 | is also normal for \s-1HPPA\s0 shared libraries to have undefined symbols. | |
506eee22 NC |
860 | .Ip "\f(CW\*(C`\-\-no\-warn\-mismatch\*(C'\fR" 4 |
861 | .IX Item "--no-warn-mismatch" | |
862 | Normally \f(CW\*(C`ld\*(C'\fR will give an error if you try to link together input | |
0285c67d NC |
863 | files that are mismatched for some reason, perhaps because they have |
864 | been compiled for different processors or for different endiannesses. | |
506eee22 | 865 | This option tells \f(CW\*(C`ld\*(C'\fR that it should silently permit such possible |
0285c67d NC |
866 | errors. This option should only be used with care, in cases when you |
867 | have taken some special action that ensures that the linker errors are | |
868 | inappropriate. | |
506eee22 NC |
869 | .Ip "\f(CW\*(C`\-\-no\-whole\-archive\*(C'\fR" 4 |
870 | .IX Item "--no-whole-archive" | |
871 | Turn off the effect of the \f(CW\*(C`\-\-whole\-archive\*(C'\fR option for subsequent | |
0285c67d | 872 | archive files. |
506eee22 NC |
873 | .Ip "\f(CW\*(C`\-\-noinhibit\-exec\*(C'\fR" 4 |
874 | .IX Item "--noinhibit-exec" | |
0285c67d | 875 | Retain the executable output file whenever it is still usable. |
252b5132 | 876 | Normally, the linker will not produce an output file if it encounters |
0285c67d NC |
877 | errors during the link process; it exits without writing an output file |
878 | when it issues any error whatsoever. | |
506eee22 NC |
879 | .Ip "\f(CW\*(C`\-\-oformat \f(CIoutput\-format\f(CW\*(C'\fR" 4 |
880 | .IX Item "--oformat output-format" | |
881 | \&\f(CW\*(C`ld\*(C'\fR may be configured to support more than one kind of object | |
882 | file. If your \f(CW\*(C`ld\*(C'\fR is configured this way, you can use the | |
883 | \&\fB\*(--oformat\fR option to specify the binary format for the output | |
884 | object file. Even when \f(CW\*(C`ld\*(C'\fR is configured to support alternative | |
885 | object formats, you don't usually need to specify this, as \f(CW\*(C`ld\*(C'\fR | |
0285c67d NC |
886 | should be configured to produce as a default output format the most |
887 | usual format on each machine. \fIoutput-format\fR is a text string, the | |
888 | name of a particular format supported by the \s-1BFD\s0 libraries. (You can | |
889 | list the available binary formats with \fBobjdump \-i\fR.) The script | |
506eee22 | 890 | command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but |
0285c67d | 891 | this option overrides it. |
506eee22 NC |
892 | .Ip "\f(CW\*(C`\-qmagic\*(C'\fR" 4 |
893 | .IX Item "-qmagic" | |
0285c67d | 894 | This option is ignored for Linux compatibility. |
506eee22 NC |
895 | .Ip "\f(CW\*(C`\-Qy\*(C'\fR" 4 |
896 | .IX Item "-Qy" | |
0285c67d | 897 | This option is ignored for \s-1SVR4\s0 compatibility. |
506eee22 NC |
898 | .Ip "\f(CW\*(C`\-\-relax\*(C'\fR" 4 |
899 | .IX Item "--relax" | |
0285c67d NC |
900 | An option with machine dependent effects. |
901 | This option is only supported on a few targets. | |
902 | .Sp | |
506eee22 | 903 | On some platforms, the \fB\*(--relax\fR option performs global |
0285c67d NC |
904 | optimizations that become possible when the linker resolves addressing |
905 | in the program, such as relaxing address modes and synthesizing new | |
906 | instructions in the output object file. | |
907 | .Sp | |
908 | On some platforms these link time global optimizations may make symbolic | |
909 | debugging of the resulting executable impossible. | |
910 | This is known to be | |
911 | the case for the Matsushita \s-1MN10200\s0 and \s-1MN10300\s0 family of processors. | |
912 | .Sp | |
506eee22 | 913 | On platforms where this is not supported, \fB\*(--relax\fR is accepted, |
0285c67d | 914 | but ignored. |
506eee22 NC |
915 | .Ip "\f(CW\*(C`\-\-retain\-symbols\-file \f(CIfilename\f(CW\*(C'\fR" 4 |
916 | .IX Item "--retain-symbols-file filename" | |
0285c67d NC |
917 | Retain \fIonly\fR the symbols listed in the file \fIfilename\fR, |
918 | discarding all others. \fIfilename\fR is simply a flat file, with one | |
919 | symbol name per line. This option is especially useful in environments | |
920 | (such as VxWorks) | |
921 | where a large global symbol table is accumulated gradually, to conserve | |
922 | run-time memory. | |
923 | .Sp | |
506eee22 | 924 | \&\fB\*(--retain-symbols-file\fR does \fInot\fR discard undefined symbols, |
0285c67d NC |
925 | or symbols needed for relocations. |
926 | .Sp | |
506eee22 | 927 | You may only specify \fB\*(--retain-symbols-file\fR once in the command |
0285c67d | 928 | line. It overrides \fB\-s\fR and \fB\-S\fR. |
506eee22 NC |
929 | .Ip "\f(CW\*(C`\-rpath \f(CIdir\f(CW\*(C'\fR" 4 |
930 | .IX Item "-rpath dir" | |
252b5132 | 931 | Add a directory to the runtime library search path. This is used when |
506eee22 | 932 | linking an \s-1ELF\s0 executable with shared objects. All \f(CW\*(C`\-rpath\*(C'\fR |
252b5132 | 933 | arguments are concatenated and passed to the runtime linker, which uses |
506eee22 | 934 | them to locate shared objects at runtime. The \f(CW\*(C`\-rpath\*(C'\fR option is |
0285c67d NC |
935 | also used when locating shared objects which are needed by shared |
936 | objects explicitly included in the link; see the description of the | |
506eee22 NC |
937 | \&\f(CW\*(C`\-rpath\-link\*(C'\fR option. If \f(CW\*(C`\-rpath\*(C'\fR is not used when linking an |
938 | \&\s-1ELF\s0 executable, the contents of the environment variable | |
939 | \&\f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it is defined. | |
0285c67d | 940 | .Sp |
506eee22 | 941 | The \f(CW\*(C`\-rpath\*(C'\fR option may also be used on SunOS. By default, on |
0285c67d | 942 | SunOS, the linker will form a runtime search patch out of all the |
506eee22 NC |
943 | \&\f(CW\*(C`\-L\*(C'\fR options it is given. If a \f(CW\*(C`\-rpath\*(C'\fR option is used, the |
944 | runtime search path will be formed exclusively using the \f(CW\*(C`\-rpath\*(C'\fR | |
945 | options, ignoring the \f(CW\*(C`\-L\*(C'\fR options. This can be useful when using | |
946 | gcc, which adds many \f(CW\*(C`\-L\*(C'\fR options which may be on \s-1NFS\s0 mounted | |
0285c67d NC |
947 | filesystems. |
948 | .Sp | |
506eee22 | 949 | For compatibility with other \s-1ELF\s0 linkers, if the \f(CW\*(C`\-R\*(C'\fR option is |
0285c67d | 950 | followed by a directory name, rather than a file name, it is treated as |
506eee22 NC |
951 | the \f(CW\*(C`\-rpath\*(C'\fR option. |
952 | .Ip "\f(CW\*(C`\-rpath\-link \f(CI\s\-1DIR\s0\f(CW\*(C'\fR" 4 | |
953 | .IX Item "-rpath-link DIR" | |
0285c67d | 954 | When using \s-1ELF\s0 or SunOS, one shared library may require another. This |
506eee22 | 955 | happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one |
0285c67d NC |
956 | of the input files. |
957 | .Sp | |
252b5132 | 958 | When the linker encounters such a dependency when doing a non-shared, |
0285c67d | 959 | non-relocatable link, it will automatically try to locate the required |
252b5132 | 960 | shared library and include it in the link, if it is not included |
506eee22 | 961 | explicitly. In such a case, the \f(CW\*(C`\-rpath\-link\*(C'\fR option |
0285c67d | 962 | specifies the first set of directories to search. The |
506eee22 | 963 | \&\f(CW\*(C`\-rpath\-link\*(C'\fR option may specify a sequence of directory names |
0285c67d NC |
964 | either by specifying a list of names separated by colons, or by |
965 | appearing multiple times. | |
966 | .Sp | |
967 | This option should be used with caution as it overrides the search path | |
968 | that may have been hard compiled into a shared library. In such a case it | |
969 | is possible to use unintentionally a different search path than the | |
970 | runtime linker would do. | |
971 | .Sp | |
972 | The linker uses the following search paths to locate required shared | |
973 | libraries. | |
506eee22 NC |
974 | .RS 4 |
975 | .Ip "1." 4 | |
976 | Any directories specified by \f(CW\*(C`\-rpath\-link\*(C'\fR options. | |
977 | .Ip "2." 4 | |
978 | Any directories specified by \f(CW\*(C`\-rpath\*(C'\fR options. The difference | |
979 | between \f(CW\*(C`\-rpath\*(C'\fR and \f(CW\*(C`\-rpath\-link\*(C'\fR is that directories | |
980 | specified by \f(CW\*(C`\-rpath\*(C'\fR options are included in the executable and | |
981 | used at runtime, whereas the \f(CW\*(C`\-rpath\-link\*(C'\fR option is only effective | |
0285c67d | 982 | at link time. It is for the native linker only. |
506eee22 NC |
983 | .Ip "3." 4 |
984 | On an \s-1ELF\s0 system, if the \f(CW\*(C`\-rpath\*(C'\fR and \f(CW\*(C`rpath\-link\*(C'\fR options | |
0285c67d | 985 | were not used, search the contents of the environment variable |
506eee22 NC |
986 | \&\f(CW\*(C`LD_RUN_PATH\*(C'\fR. It is for the native linker only. |
987 | .Ip "4." 4 | |
988 | On SunOS, if the \f(CW\*(C`\-rpath\*(C'\fR option was not used, search any | |
989 | directories specified using \f(CW\*(C`\-L\*(C'\fR options. | |
990 | .Ip "5." 4 | |
0285c67d | 991 | For a native linker, the contents of the environment variable |
506eee22 NC |
992 | \&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR. |
993 | .Ip "6." 4 | |
994 | For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or | |
995 | \&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared | |
996 | libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if | |
997 | \&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist. | |
998 | .Ip "7." 4 | |
0285c67d | 999 | The default directories, normally \fI/lib\fR and \fI/usr/lib\fR. |
506eee22 | 1000 | .Ip "8." 4 |
0285c67d NC |
1001 | For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR |
1002 | exists, the list of directories found in that file. | |
506eee22 NC |
1003 | .RE |
1004 | .RS 4 | |
0285c67d | 1005 | .Sp |
252b5132 RH |
1006 | If the required shared library is not found, the linker will issue a |
1007 | warning and continue with the link. | |
506eee22 NC |
1008 | .RE |
1009 | .Ip "\f(CW\*(C`\-shared\*(C'\fR" 4 | |
1010 | .IX Item "-shared" | |
1011 | .Ip "\f(CW\*(C`\-Bshareable\*(C'\fR" 4 | |
1012 | .IX Item "-Bshareable" | |
0285c67d NC |
1013 | Create a shared library. This is currently only supported on \s-1ELF\s0, \s-1XCOFF\s0 |
1014 | and SunOS platforms. On SunOS, the linker will automatically create a | |
506eee22 | 1015 | shared library if the \f(CW\*(C`\-e\*(C'\fR option is not used and there are |
0285c67d | 1016 | undefined symbols in the link. |
506eee22 NC |
1017 | .Ip "\f(CW\*(C`\-\-sort\-common\*(C'\fR" 4 |
1018 | .IX Item "--sort-common" | |
1019 | This option tells \f(CW\*(C`ld\*(C'\fR to sort the common symbols by size when it | |
0285c67d NC |
1020 | places them in the appropriate output sections. First come all the one |
1021 | byte symbols, then all the two bytes, then all the four bytes, and then | |
1022 | everything else. This is to prevent gaps between symbols due to | |
1023 | alignment constraints. | |
506eee22 NC |
1024 | .Ip "\f(CW\*(C`\-\-split\-by\-file [\f(CIsize\f(CW]\*(C'\fR" 4 |
1025 | .IX Item "--split-by-file [size]" | |
1026 | Similar to \f(CW\*(C`\-\-split\-by\-reloc\*(C'\fR but creates a new output section for | |
0285c67d NC |
1027 | each input file when \fIsize\fR is reached. \fIsize\fR defaults to a |
1028 | size of 1 if not given. | |
506eee22 NC |
1029 | .Ip "\f(CW\*(C`\-\-split\-by\-reloc [\f(CIcount\f(CW]\*(C'\fR" 4 |
1030 | .IX Item "--split-by-reloc [count]" | |
0285c67d NC |
1031 | Tries to creates extra sections in the output file so that no single |
1032 | output section in the file contains more than \fIcount\fR relocations. | |
1033 | This is useful when generating huge relocatable files for downloading into | |
1034 | certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0 | |
1035 | cannot represent more than 65535 relocations in a single section. Note | |
1036 | that this will fail to work with object file formats which do not | |
252b5132 | 1037 | support arbitrary sections. The linker will not split up individual |
0285c67d NC |
1038 | input sections for redistribution, so if a single input section contains |
1039 | more than \fIcount\fR relocations one output section will contain that | |
1040 | many relocations. \fIcount\fR defaults to a value of 32768. | |
506eee22 NC |
1041 | .Ip "\f(CW\*(C`\-\-stats\*(C'\fR" 4 |
1042 | .IX Item "--stats" | |
0285c67d NC |
1043 | Compute and display statistics about the operation of the linker, such |
1044 | as execution time and memory usage. | |
506eee22 NC |
1045 | .Ip "\f(CW\*(C`\-\-traditional\-format\*(C'\fR" 4 |
1046 | .IX Item "--traditional-format" | |
1047 | For some targets, the output of \f(CW\*(C`ld\*(C'\fR is different in some ways from | |
1048 | the output of some existing linker. This switch requests \f(CW\*(C`ld\*(C'\fR to | |
0285c67d NC |
1049 | use the traditional format instead. |
1050 | .Sp | |
506eee22 | 1051 | For example, on SunOS, \f(CW\*(C`ld\*(C'\fR combines duplicate entries in the |
0285c67d NC |
1052 | symbol string table. This can reduce the size of an output file with |
1053 | full debugging information by over 30 percent. Unfortunately, the SunOS | |
506eee22 NC |
1054 | \&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no |
1055 | trouble). The \fB\*(--traditional-format\fR switch tells \f(CW\*(C`ld\*(C'\fR to not | |
0285c67d | 1056 | combine duplicate entries. |
506eee22 NC |
1057 | .Ip "\f(CW\*(C`\-\-section\-start \f(CIsectionname\f(CW=\f(CIorg\f(CW\*(C'\fR" 4 |
1058 | .IX Item "--section-start sectionname=org" | |
176355da | 1059 | Locate a section in the output file at the absolute |
0285c67d | 1060 | address given by \fIorg\fR. You may use this option as many |
176355da | 1061 | times as necessary to locate multiple sections in the command |
0285c67d | 1062 | line. |
506eee22 | 1063 | \&\fIorg\fR must be a single hexadecimal integer; |
0285c67d | 1064 | for compatibility with other linkers, you may omit the leading |
506eee22 | 1065 | \&\fB0x\fR usually associated with hexadecimal values. \fINote:\fR there |
0285c67d NC |
1066 | should be no white space between \fIsectionname\fR, the equals |
1067 | sign (``\fB=\fR''), and \fIorg\fR. | |
506eee22 NC |
1068 | .Ip "\f(CW\*(C`\-Tbss \f(CIorg\f(CW\*(C'\fR" 4 |
1069 | .IX Item "-Tbss org" | |
1070 | .Ip "\f(CW\*(C`\-Tdata \f(CIorg\f(CW\*(C'\fR" 4 | |
1071 | .IX Item "-Tdata org" | |
1072 | .Ip "\f(CW\*(C`\-Ttext \f(CIorg\f(CW\*(C'\fR" 4 | |
1073 | .IX Item "-Ttext org" | |
1074 | Use \fIorg\fR as the starting address for\-\-\-respectively\-\-\-the | |
1075 | \&\f(CW\*(C`bss\*(C'\fR, \f(CW\*(C`data\*(C'\fR, or the \f(CW\*(C`text\*(C'\fR segment of the output file. | |
1076 | \&\fIorg\fR must be a single hexadecimal integer; | |
0285c67d | 1077 | for compatibility with other linkers, you may omit the leading |
506eee22 NC |
1078 | \&\fB0x\fR usually associated with hexadecimal values. |
1079 | .Ip "\f(CW\*(C`\-\-dll\-verbose\*(C'\fR" 4 | |
1080 | .IX Item "--dll-verbose" | |
1081 | .Ip "\f(CW\*(C`\-\-verbose\*(C'\fR" 4 | |
1082 | .IX Item "--verbose" | |
1083 | Display the version number for \f(CW\*(C`ld\*(C'\fR and list the linker emulations | |
0285c67d NC |
1084 | supported. Display which input files can and cannot be opened. Display |
1085 | the linker script if using a default builtin script. | |
506eee22 NC |
1086 | .Ip "\f(CW\*(C`\-\-version\-script=\f(CIversion\-scriptfile\f(CW\*(C'\fR" 4 |
1087 | .IX Item "--version-script=version-scriptfile" | |
0285c67d NC |
1088 | Specify the name of a version script to the linker. This is typically |
1089 | used when creating shared libraries to specify additional information | |
1090 | about the version heirarchy for the library being created. This option | |
1091 | is only meaningful on \s-1ELF\s0 platforms which support shared libraries. | |
506eee22 NC |
1092 | .Ip "\f(CW\*(C`\-\-warn\-common\*(C'\fR" 4 |
1093 | .IX Item "--warn-common" | |
252b5132 RH |
1094 | Warn when a common symbol is combined with another common symbol or with |
1095 | a symbol definition. Unix linkers allow this somewhat sloppy practice, | |
1096 | but linkers on some other operating systems do not. This option allows | |
1097 | you to find potential problems from combining global symbols. | |
0285c67d NC |
1098 | Unfortunately, some C libraries use this practice, so you may get some |
1099 | warnings about symbols in the libraries as well as in your programs. | |
1100 | .Sp | |
1101 | There are three kinds of global symbols, illustrated here by C examples: | |
506eee22 NC |
1102 | .RS 4 |
1103 | .Ip "\fBint i = 1;\fR" 4 | |
1104 | .IX Item "int i = 1;" | |
0285c67d NC |
1105 | A definition, which goes in the initialized data section of the output |
1106 | file. | |
506eee22 NC |
1107 | .Ip "\fBextern int i;\fR" 4 |
1108 | .IX Item "extern int i;" | |
0285c67d NC |
1109 | An undefined reference, which does not allocate space. |
1110 | There must be either a definition or a common symbol for the | |
1111 | variable somewhere. | |
506eee22 NC |
1112 | .Ip "\fBint i;\fR" 4 |
1113 | .IX Item "int i;" | |
0285c67d NC |
1114 | A common symbol. If there are only (one or more) common symbols for a |
1115 | variable, it goes in the uninitialized data area of the output file. | |
1116 | The linker merges multiple common symbols for the same variable into a | |
1117 | single symbol. If they are of different sizes, it picks the largest | |
1118 | size. The linker turns a common symbol into a declaration, if there is | |
1119 | a definition of the same variable. | |
506eee22 NC |
1120 | .RE |
1121 | .RS 4 | |
0285c67d | 1122 | .Sp |
506eee22 | 1123 | The \fB\*(--warn-common\fR option can produce five kinds of warnings. |
0285c67d NC |
1124 | Each warning consists of a pair of lines: the first describes the symbol |
1125 | just encountered, and the second describes the previous symbol | |
1126 | encountered with the same name. One or both of the two symbols will be | |
1127 | a common symbol. | |
506eee22 NC |
1128 | .RS 4 |
1129 | .RE | |
1130 | .Ip "1." 4 | |
0285c67d NC |
1131 | Turning a common symbol into a reference, because there is already a |
1132 | definition for the symbol. | |
506eee22 NC |
1133 | .Sp |
1134 | .Vb 3 | |
1135 | \& I<file>(I<section>): warning: common of `I<symbol>' | |
1136 | \& overridden by definition | |
1137 | \& I<file>(I<section>): warning: defined here | |
1138 | .Ve | |
1139 | .Ip "2." 4 | |
0285c67d NC |
1140 | Turning a common symbol into a reference, because a later definition for |
1141 | the symbol is encountered. This is the same as the previous case, | |
1142 | except that the symbols are encountered in a different order. | |
506eee22 NC |
1143 | .Sp |
1144 | .Vb 3 | |
1145 | \& I<file>(I<section>): warning: definition of `I<symbol>' | |
1146 | \& overriding common | |
1147 | \& I<file>(I<section>): warning: common is here | |
1148 | .Ve | |
1149 | .Ip "3." 4 | |
0285c67d | 1150 | Merging a common symbol with a previous same-sized common symbol. |
506eee22 NC |
1151 | .Sp |
1152 | .Vb 3 | |
1153 | \& I<file>(I<section>): warning: multiple common | |
1154 | \& of `I<symbol>' | |
1155 | \& I<file>(I<section>): warning: previous common is here | |
1156 | .Ve | |
1157 | .Ip "4." 4 | |
0285c67d | 1158 | Merging a common symbol with a previous larger common symbol. |
506eee22 NC |
1159 | .Sp |
1160 | .Vb 3 | |
1161 | \& I<file>(I<section>): warning: common of `I<symbol>' | |
1162 | \& overridden by larger common | |
1163 | \& I<file>(I<section>): warning: larger common is here | |
1164 | .Ve | |
1165 | .Ip "5." 4 | |
0285c67d NC |
1166 | Merging a common symbol with a previous smaller common symbol. This is |
1167 | the same as the previous case, except that the symbols are | |
1168 | encountered in a different order. | |
506eee22 NC |
1169 | .Sp |
1170 | .Vb 3 | |
1171 | \& I<file>(I<section>): warning: common of `I<symbol>' | |
1172 | \& overriding smaller common | |
1173 | \& I<file>(I<section>): warning: smaller common is here | |
1174 | .Ve | |
1175 | .RE | |
1176 | .RS 4 | |
1177 | .RE | |
1178 | .Ip "\f(CW\*(C`\-\-warn\-constructors\*(C'\fR" 4 | |
1179 | .IX Item "--warn-constructors" | |
0285c67d NC |
1180 | Warn if any global constructors are used. This is only useful for a few |
1181 | object file formats. For formats like \s-1COFF\s0 or \s-1ELF\s0, the linker can not | |
1182 | detect the use of global constructors. | |
506eee22 NC |
1183 | .Ip "\f(CW\*(C`\-\-warn\-multiple\-gp\*(C'\fR" 4 |
1184 | .IX Item "--warn-multiple-gp" | |
0285c67d NC |
1185 | Warn if multiple global pointer values are required in the output file. |
1186 | This is only meaningful for certain processors, such as the Alpha. | |
1187 | Specifically, some processors put large-valued constants in a special | |
1188 | section. A special register (the global pointer) points into the middle | |
1189 | of this section, so that constants can be loaded efficiently via a | |
1190 | base-register relative addressing mode. Since the offset in | |
1191 | base-register relative mode is fixed and relatively small (e.g., 16 | |
1192 | bits), this limits the maximum size of the constant pool. Thus, in | |
1193 | large programs, it is often necessary to use multiple global pointer | |
1194 | values in order to be able to address all possible constants. This | |
1195 | option causes a warning to be issued whenever this case occurs. | |
506eee22 NC |
1196 | .Ip "\f(CW\*(C`\-\-warn\-once\*(C'\fR" 4 |
1197 | .IX Item "--warn-once" | |
252b5132 RH |
1198 | Only warn once for each undefined symbol, rather than once per module |
1199 | which refers to it. | |
506eee22 NC |
1200 | .Ip "\f(CW\*(C`\-\-warn\-section\-align\*(C'\fR" 4 |
1201 | .IX Item "--warn-section-align" | |
252b5132 RH |
1202 | Warn if the address of an output section is changed because of |
1203 | alignment. Typically, the alignment will be set by an input section. | |
1204 | The address will only be changed if it not explicitly specified; that | |
506eee22 | 1205 | is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for |
0285c67d | 1206 | the section. |
506eee22 NC |
1207 | .Ip "\f(CW\*(C`\-\-whole\-archive\*(C'\fR" 4 |
1208 | .IX Item "--whole-archive" | |
252b5132 | 1209 | For each archive mentioned on the command line after the |
506eee22 | 1210 | \&\f(CW\*(C`\-\-whole\-archive\*(C'\fR option, include every object file in the archive |
0285c67d NC |
1211 | in the link, rather than searching the archive for the required object |
1212 | files. This is normally used to turn an archive file into a shared | |
1213 | library, forcing every object to be included in the resulting shared | |
1214 | library. This option may be used more than once. | |
1215 | .Sp | |
1216 | Two notes when using this option from gcc: First, gcc doesn't know | |
506eee22 NC |
1217 | about this option, so you have to use \f(CW\*(C`\-Wl,\-whole\-archive\*(C'\fR. |
1218 | Second, don't forget to use \f(CW\*(C`\-Wl,\-no\-whole\-archive\*(C'\fR after your | |
0285c67d NC |
1219 | list of archives, because gcc will add its own list of archives to |
1220 | your link and you may not want this flag to affect those as well. | |
506eee22 NC |
1221 | .Ip "\f(CW\*(C`\-\-wrap \f(CIsymbol\f(CW\*(C'\fR" 4 |
1222 | .IX Item "--wrap symbol" | |
0285c67d | 1223 | Use a wrapper function for \fIsymbol\fR. Any undefined reference to |
506eee22 NC |
1224 | \&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. Any |
1225 | undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR will be resolved to | |
1226 | \&\fIsymbol\fR. | |
0285c67d NC |
1227 | .Sp |
1228 | This can be used to provide a wrapper for a system function. The | |
506eee22 | 1229 | wrapper function should be called \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. If it |
0285c67d | 1230 | wishes to call the system function, it should call |
506eee22 | 1231 | \&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR. |
0285c67d NC |
1232 | .Sp |
1233 | Here is a trivial example: | |
1234 | .Sp | |
506eee22 | 1235 | .Vb 6 |
0285c67d NC |
1236 | \& void * |
1237 | \& __wrap_malloc (int c) | |
1238 | \& { | |
1239 | \& printf ("malloc called with %ld\en", c); | |
1240 | \& return __real_malloc (c); | |
1241 | \& } | |
1242 | .Ve | |
506eee22 NC |
1243 | If you link other code with this file using \f(CW\*(C`\-\-wrap malloc\*(C'\fR, then |
1244 | all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR | |
1245 | instead. The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will | |
1246 | call the real \f(CW\*(C`malloc\*(C'\fR function. | |
0285c67d | 1247 | .Sp |
506eee22 NC |
1248 | You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that |
1249 | links without the \f(CW\*(C`\-\-wrap\*(C'\fR option will succeed. If you do this, | |
1250 | you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same | |
1251 | file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the | |
1252 | call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR. | |
1253 | .Ip "\f(CW\*(C`\-\-enable\-new\-dtags\*(C'\fR" 4 | |
1254 | .IX Item "--enable-new-dtags" | |
1255 | .Ip "\f(CW\*(C`\-\-disable\-new\-dtags\*(C'\fR" 4 | |
1256 | .IX Item "--disable-new-dtags" | |
0285c67d NC |
1257 | This linker can create the new dynamic tags in \s-1ELF\s0. But the older \s-1ELF\s0 |
1258 | systems may not understand them. If you specify | |
506eee22 NC |
1259 | \&\f(CW\*(C`\-\-enable\-new\-dtags\*(C'\fR, the dynamic tags will be created as needed. |
1260 | If you specify \f(CW\*(C`\-\-disable\-new\-dtags\*(C'\fR, no new dynamic tags will be | |
0285c67d NC |
1261 | created. By default, the new dynamic tags are not created. Note that |
1262 | those options are only available for \s-1ELF\s0 systems. | |
1263 | .PP | |
506eee22 | 1264 | The i386 \s-1PE\s0 linker supports the \f(CW\*(C`\-shared\*(C'\fR option, which causes |
0285c67d | 1265 | the output to be a dynamically linked library (\s-1DLL\s0) instead of a |
506eee22 | 1266 | normal executable. You should name the output \f(CW\*(C`*.dll\*(C'\fR when you |
0285c67d | 1267 | use this option. In addition, the linker fully supports the standard |
506eee22 | 1268 | \&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line |
0285c67d NC |
1269 | like an object file (in fact, it should precede archives it exports |
1270 | symbols from, to ensure that they get linked in, just like a normal | |
1271 | object file). | |
1272 | .PP | |
1273 | In addition to the options common to all targets, the i386 \s-1PE\s0 linker | |
1274 | support additional command line options that are specific to the i386 | |
506eee22 | 1275 | \&\s-1PE\s0 target. Options that take values may be separated from their |
0285c67d | 1276 | values by either a space or an equals sign. |
506eee22 NC |
1277 | .Ip "\f(CW\*(C`\-\-add\-stdcall\-alias\*(C'\fR" 4 |
1278 | .IX Item "--add-stdcall-alias" | |
0285c67d NC |
1279 | If given, symbols with a stdcall suffix (@\fInn\fR) will be exported |
1280 | as-is and also with the suffix stripped. | |
506eee22 NC |
1281 | .Ip "\f(CW\*(C`\-\-base\-file \f(CIfile\f(CW\*(C'\fR" 4 |
1282 | .IX Item "--base-file file" | |
0285c67d NC |
1283 | Use \fIfile\fR as the name of a file in which to save the base |
1284 | addresses of all the relocations needed for generating DLLs with | |
506eee22 NC |
1285 | \&\fIdlltool\fR. |
1286 | .Ip "\f(CW\*(C`\-\-dll\*(C'\fR" 4 | |
1287 | .IX Item "--dll" | |
0285c67d | 1288 | Create a \s-1DLL\s0 instead of a regular executable. You may also use |
506eee22 | 1289 | \&\f(CW\*(C`\-shared\*(C'\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR |
0285c67d | 1290 | file. |
506eee22 NC |
1291 | .Ip "\f(CW\*(C`\-\-enable\-stdcall\-fixup\*(C'\fR" 4 |
1292 | .IX Item "--enable-stdcall-fixup" | |
1293 | .Ip "\f(CW\*(C`\-\-disable\-stdcall\-fixup\*(C'\fR" 4 | |
1294 | .IX Item "--disable-stdcall-fixup" | |
0285c67d NC |
1295 | If the link finds a symbol that it cannot resolve, it will attempt to |
1296 | do \*(L"fuzzy linking\*(R" by looking for another defined symbol that differs | |
1297 | only in the format of the symbol name (cdecl vs stdcall) and will | |
1298 | resolve that symbol by linking to the match. For example, the | |
506eee22 NC |
1299 | undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function |
1300 | \&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked | |
1301 | to the function \f(CW\*(C`_bar\*(C'\fR. When the linker does this, it prints a | |
0285c67d NC |
1302 | warning, since it normally should have failed to link, but sometimes |
1303 | import libraries generated from third-party dlls may need this feature | |
506eee22 | 1304 | to be usable. If you specify \f(CW\*(C`\-\-enable\-stdcall\-fixup\*(C'\fR, this |
0285c67d | 1305 | feature is fully enabled and warnings are not printed. If you specify |
506eee22 | 1306 | \&\f(CW\*(C`\-\-disable\-stdcall\-fixup\*(C'\fR, this feature is disabled and such |
0285c67d | 1307 | mismatches are considered to be errors. |
506eee22 NC |
1308 | .Ip "\f(CW\*(C`\-\-export\-all\-symbols\*(C'\fR" 4 |
1309 | .IX Item "--export-all-symbols" | |
0285c67d NC |
1310 | If given, all global symbols in the objects used to build a \s-1DLL\s0 will |
1311 | be exported by the \s-1DLL\s0. Note that this is the default if there | |
1312 | otherwise wouldn't be any exported symbols. When symbols are | |
1313 | explicitly exported via \s-1DEF\s0 files or implicitly exported via function | |
1314 | attributes, the default is to not export anything else unless this | |
506eee22 NC |
1315 | option is given. Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR, |
1316 | \&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, and \f(CW\*(C`impure_ptr\*(C'\fR will not be automatically | |
0285c67d | 1317 | exported. |
506eee22 NC |
1318 | .Ip "\f(CW\*(C`\-\-exclude\-symbols \f(CIsymbol\f(CW,\f(CIsymbol\f(CW,...\*(C'\fR" 4 |
1319 | .IX Item "--exclude-symbols symbol,symbol,..." | |
0285c67d NC |
1320 | Specifies a list of symbols which should not be automatically |
1321 | exported. The symbol names may be delimited by commas or colons. | |
506eee22 NC |
1322 | .Ip "\f(CW\*(C`\-\-file\-alignment\*(C'\fR" 4 |
1323 | .IX Item "--file-alignment" | |
0285c67d NC |
1324 | Specify the file alignment. Sections in the file will always begin at |
1325 | file offsets which are multiples of this number. This defaults to | |
1326 | 512. | |
506eee22 NC |
1327 | .Ip "\f(CW\*(C`\-\-heap \f(CIreserve\f(CW\*(C'\fR" 4 |
1328 | .IX Item "--heap reserve" | |
1329 | .Ip "\f(CW\*(C`\-\-heap \f(CIreserve\f(CW,\f(CIcommit\f(CW\*(C'\fR" 4 | |
1330 | .IX Item "--heap reserve,commit" | |
0285c67d NC |
1331 | Specify the amount of memory to reserve (and optionally commit) to be |
1332 | used as heap for this program. The default is 1Mb reserved, 4K | |
1333 | committed. | |
506eee22 NC |
1334 | .Ip "\f(CW\*(C`\-\-image\-base \f(CIvalue\f(CW\*(C'\fR" 4 |
1335 | .IX Item "--image-base value" | |
0285c67d NC |
1336 | Use \fIvalue\fR as the base address of your program or dll. This is |
1337 | the lowest memory location that will be used when your program or dll | |
1338 | is loaded. To reduce the need to relocate and improve performance of | |
1339 | your dlls, each should have a unique base address and not overlap any | |
1340 | other dlls. The default is 0x400000 for executables, and 0x10000000 | |
1341 | for dlls. | |
506eee22 NC |
1342 | .Ip "\f(CW\*(C`\-\-kill\-at\*(C'\fR" 4 |
1343 | .IX Item "--kill-at" | |
0285c67d NC |
1344 | If given, the stdcall suffixes (@\fInn\fR) will be stripped from |
1345 | symbols before they are exported. | |
506eee22 NC |
1346 | .Ip "\f(CW\*(C`\-\-major\-image\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
1347 | .IX Item "--major-image-version value" | |
0285c67d | 1348 | Sets the major number of the \*(L"image version\*(R". Defaults to 1. |
506eee22 NC |
1349 | .Ip "\f(CW\*(C`\-\-major\-os\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
1350 | .IX Item "--major-os-version value" | |
0285c67d | 1351 | Sets the major number of the \*(L"os version\*(R". Defaults to 4. |
506eee22 NC |
1352 | .Ip "\f(CW\*(C`\-\-major\-subsystem\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
1353 | .IX Item "--major-subsystem-version value" | |
0285c67d | 1354 | Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4. |
506eee22 NC |
1355 | .Ip "\f(CW\*(C`\-\-minor\-image\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
1356 | .IX Item "--minor-image-version value" | |
0285c67d | 1357 | Sets the minor number of the \*(L"image version\*(R". Defaults to 0. |
506eee22 NC |
1358 | .Ip "\f(CW\*(C`\-\-minor\-os\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
1359 | .IX Item "--minor-os-version value" | |
0285c67d | 1360 | Sets the minor number of the \*(L"os version\*(R". Defaults to 0. |
506eee22 NC |
1361 | .Ip "\f(CW\*(C`\-\-minor\-subsystem\-version \f(CIvalue\f(CW\*(C'\fR" 4 |
1362 | .IX Item "--minor-subsystem-version value" | |
0285c67d | 1363 | Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0. |
506eee22 NC |
1364 | .Ip "\f(CW\*(C`\-\-output\-def \f(CIfile\f(CW\*(C'\fR" 4 |
1365 | .IX Item "--output-def file" | |
0285c67d NC |
1366 | The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0 |
1367 | file corresponding to the \s-1DLL\s0 the linker is generating. This \s-1DEF\s0 file | |
506eee22 NC |
1368 | (which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import |
1369 | library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to | |
0285c67d | 1370 | automatically or implicitly exported symbols. |
506eee22 NC |
1371 | .Ip "\f(CW\*(C`\-\-section\-alignment\*(C'\fR" 4 |
1372 | .IX Item "--section-alignment" | |
0285c67d NC |
1373 | Sets the section alignment. Sections in memory will always begin at |
1374 | addresses which are a multiple of this number. Defaults to 0x1000. | |
506eee22 NC |
1375 | .Ip "\f(CW\*(C`\-\-stack \f(CIreserve\f(CW\*(C'\fR" 4 |
1376 | .IX Item "--stack reserve" | |
1377 | .Ip "\f(CW\*(C`\-\-stack \f(CIreserve\f(CW,\f(CIcommit\f(CW\*(C'\fR" 4 | |
1378 | .IX Item "--stack reserve,commit" | |
0285c67d NC |
1379 | Specify the amount of memory to reserve (and optionally commit) to be |
1380 | used as stack for this program. The default is 32Mb reserved, 4K | |
1381 | committed. | |
506eee22 NC |
1382 | .Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW\*(C'\fR" 4 |
1383 | .IX Item "--subsystem which" | |
1384 | .Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW:\f(CImajor\f(CW\*(C'\fR" 4 | |
1385 | .IX Item "--subsystem which:major" | |
1386 | .Ip "\f(CW\*(C`\-\-subsystem \f(CIwhich\f(CW:\f(CImajor\f(CW.\f(CIminor\f(CW\*(C'\fR" 4 | |
1387 | .IX Item "--subsystem which:major.minor" | |
0285c67d | 1388 | Specifies the subsystem under which your program will execute. The |
506eee22 NC |
1389 | legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR, |
1390 | \&\f(CW\*(C`console\*(C'\fR, and \f(CW\*(C`posix\*(C'\fR. You may optionally set the | |
0285c67d NC |
1391 | subsystem version also. |
1392 | .SH "ENVIRONMENT" | |
506eee22 NC |
1393 | .IX Header "ENVIRONMENT" |
1394 | You can change the behavior of \f(CW\*(C`ld\*(C'\fR with the environment variables | |
1395 | \&\f(CW\*(C`GNUTARGET\*(C'\fR, \f(CW\*(C`LDEMULATION\*(C'\fR, and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR. | |
0285c67d | 1396 | .PP |
506eee22 NC |
1397 | \&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't |
1398 | use \fB\-b\fR (or its synonym \fB\*(--format\fR). Its value should be one | |
1399 | of the \s-1BFD\s0 names for an input format. If there is no | |
1400 | \&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \f(CW\*(C`ld\*(C'\fR uses the natural format | |
1401 | of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then \s-1BFD\s0 | |
0285c67d NC |
1402 | attempts to discover the input format by examining binary input files; |
1403 | this method often succeeds, but there are potential ambiguities, since | |
1404 | there is no method of ensuring that the magic number used to specify | |
1405 | object-file formats is unique. However, the configuration procedure for | |
506eee22 | 1406 | \&\s-1BFD\s0 on each system places the conventional format for that system first |
0285c67d NC |
1407 | in the search-list, so ambiguities are resolved in favor of convention. |
1408 | .PP | |
506eee22 NC |
1409 | \&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the |
1410 | \&\fB\-m\fR option. The emulation can affect various aspects of linker | |
0285c67d | 1411 | behaviour, particularly the default linker script. You can list the |
506eee22 NC |
1412 | available emulations with the \fB\*(--verbose\fR or \fB\-V\fR options. If |
1413 | the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment | |
0285c67d NC |
1414 | variable is not defined, the default emulation depends upon how the |
1415 | linker was configured. | |
1416 | .PP | |
1417 | Normally, the linker will default to demangling symbols. However, if | |
506eee22 | 1418 | \&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will |
0285c67d | 1419 | default to not demangling symbols. This environment variable is used in |
506eee22 NC |
1420 | a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program. The default |
1421 | may be overridden by the \fB\*(--demangle\fR and \fB\*(--no-demangle\fR | |
0285c67d NC |
1422 | options. |
1423 | .SH "SEE ALSO" | |
506eee22 NC |
1424 | .IX Header "SEE ALSO" |
1425 | \&\fIar\fR\|(1), \fInm\fR\|(1), \fIobjcopy\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and | |
0285c67d | 1426 | the Info entries for \fIbinutils\fR and |
506eee22 | 1427 | \&\fIld\fR. |
0285c67d | 1428 | .SH "COPYRIGHT" |
506eee22 | 1429 | .IX Header "COPYRIGHT" |
0285c67d NC |
1430 | Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc. |
1431 | .PP | |
1432 | Permission is granted to copy, distribute and/or modify this document | |
506eee22 | 1433 | under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 |
0285c67d NC |
1434 | or any later version published by the Free Software Foundation; |
1435 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
1436 | Back-Cover Texts. A copy of the license is included in the | |
506eee22 | 1437 | section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R". |