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