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