Commit | Line | Data |
---|---|---|
a2b64bed NC |
1 | .\" Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, |
2 | .\" 2001 Free Software Foundation, Inc. | |
252b5132 | 3 | .\" See section COPYING for conditions for redistribution |
fd89e65f | 4 | .TH ld 1 "" "Free Software Foundation" "GNU Development Tools" |
252b5132 RH |
5 | .de BP |
6 | .sp | |
7 | .ti \-.2i | |
8 | \(** | |
9 | .. | |
10 | ||
11 | .SH NAME | |
12 | ld \- the GNU linker | |
13 | ||
14 | .SH SYNOPSIS | |
15 | .hy 0 | |
16 | .na | |
17 | .TP | |
18 | .B ld | |
19 | .RB "[\|" \-o " | |
20 | .I output\c | |
21 | \&\|] \c | |
22 | .I objfile\c | |
23 | \&.\|.\|. | |
24 | .br | |
25 | .RB "[\|" \-A\c | |
26 | .I architecture\c | |
27 | \&\|] | |
28 | .RB "[\|" "\-b\ "\c | |
29 | .I input-format\c | |
30 | \&\|] | |
31 | .RB "[\|" \-Bstatic "\|]" | |
a1ab1d2a | 32 | .RB "[\|" \-Bgroup "\|]" |
252b5132 RH |
33 | .RB "[\|" \-Bdynamic "\|]" |
34 | .RB "[\|" \-Bsymbolic "\|]" | |
35 | .RB "[\|" "\-c\ "\c | |
36 | .I commandfile\c | |
37 | \&\|] | |
38 | .RB "[\|" \-\-cref "\|]" | |
39 | .RB "[\|" \-d | \-dc | \-dp\c | |
40 | \|] | |
41 | .br | |
42 | .RB "[\|" "\-defsym\ "\c | |
43 | .I symbol\c | |
176355da | 44 | \&=\c |
252b5132 RH |
45 | .I expression\c |
46 | \&\|] | |
47 | .RB "[\|" \-\-demangle "\|]" | |
48 | .RB "[\|" \-\-no\-demangle "\|]" | |
49 | .RB "[\|" "\-e\ "\c | |
50 | .I entry\c | |
51 | \&\|] | |
52 | .RB "[\|" \-embedded\-relocs "\|]" | |
53 | .RB "[\|" \-E "\|]" | |
54 | .RB "[\|" \-export\-dynamic "\|]" | |
55 | .RB "[\|" "\-f\ "\c | |
56 | .I name\c | |
57 | \&\|] | |
58 | .RB "[\|" "\-\-auxiliary\ "\c | |
59 | .I name\c | |
60 | \&\|] | |
61 | .RB "[\|" "\-F\ "\c | |
62 | .I name\c | |
63 | \&\|] | |
64 | .RB "[\|" "\-\-filter\ "\c | |
65 | .I name\c | |
66 | \&\|] | |
67 | .RB "[\|" "\-format\ "\c | |
68 | .I input-format\c | |
69 | \&\|] | |
70 | .RB "[\|" \-g "\|]" | |
71 | .RB "[\|" \-G | |
72 | .I size\c | |
73 | \&\|] | |
74 | .RB "[\|" "\-h\ "\c | |
75 | .I name\c | |
76 | \&\|] | |
77 | .RB "[\|" "\-soname\ "\c | |
78 | .I name\c | |
79 | \&\|] | |
80 | .RB "[\|" \-\-help "\|]" | |
81 | .RB "[\|" \-i "\|]" | |
82 | .RB "[\|" \-l\c | |
83 | .I ar\c | |
84 | \&\|] | |
85 | .RB "[\|" \-L\c | |
86 | .I searchdir\c | |
87 | \&\|] | |
88 | .RB "[\|" \-M "\|]" | |
89 | .RB "[\|" \-Map | |
90 | .I mapfile\c | |
91 | \&\|] | |
92 | .RB "[\|" \-m | |
93 | .I emulation\c | |
94 | \&\|] | |
95 | .RB "[\|" \-n | \-N "\|]" | |
96 | .RB "[\|" \-noinhibit-exec "\|]" | |
97 | .RB "[\|" \-no\-keep\-memory "\|]" | |
98 | .RB "[\|" \-no\-warn\-mismatch "\|]" | |
99 | .RB "[\|" \-O\c | |
100 | .I level\c | |
101 | \&\|] | |
0088edd2 | 102 | .RB "[\|" "\--oformat\ "\c |
252b5132 RH |
103 | .I output-format\c |
104 | \&\|] | |
105 | .RB "[\|" "\-R\ "\c | |
106 | .I filename\c | |
107 | \&\|] | |
108 | .RB "[\|" \-relax "\|]" | |
109 | .RB "[\|" \-r | \-Ur "\|]" | |
110 | .RB "[\|" "\-rpath\ "\c | |
111 | .I directory\c | |
112 | \&\|] | |
113 | .RB "[\|" "\-rpath\-link\ "\c | |
114 | .I directory\c | |
115 | \&\|] | |
116 | .RB "[\|" \-S "\|]" | |
117 | .RB "[\|" \-s "\|]" | |
118 | .RB "[\|" \-shared "\|]" | |
119 | .RB "[\|" \-sort\-common "\|]" | |
120 | .RB "[\|" "\-split\-by\-reloc\ "\c | |
121 | .I count\c | |
122 | \&\|] | |
123 | .RB "[\|" \-split\-by\-file "\|]" | |
124 | .RB "[\|" "\-T\ "\c | |
125 | .I commandfile\c | |
126 | \&\|] | |
176355da NC |
127 | .RB "[\|" "\-\-section\-start\ "\c |
128 | .I sectionname\c | |
129 | \&=\c | |
130 | .I sectionorg\c | |
131 | \&\|] | |
252b5132 RH |
132 | .RB "[\|" "\-Ttext\ "\c |
133 | .I textorg\c | |
134 | \&\|] | |
135 | .RB "[\|" "\-Tdata\ "\c | |
136 | .I dataorg\c | |
137 | \&\|] | |
138 | .RB "[\|" "\-Tbss\ "\c | |
139 | .I bssorg\c | |
140 | \&\|] | |
141 | .RB "[\|" \-t "\|]" | |
142 | .RB "[\|" "\-u\ "\c | |
143 | .I sym\c | |
144 | \&] | |
145 | .RB "[\|" \-V "\|]" | |
146 | .RB "[\|" \-v "\|]" | |
147 | .RB "[\|" \-\-verbose "\|]" | |
148 | .RB "[\|" \-\-version "\|]" | |
149 | .RB "[\|" \-warn\-common "\|]" | |
150 | .RB "[\|" \-warn\-constructors "\|]" | |
151 | .RB "[\|" \-warn\-multiple\-gp "\|]" | |
152 | .RB "[\|" \-warn\-once "\|]" | |
153 | .RB "[\|" \-warn\-section\-align "\|]" | |
154 | .RB "[\|" \-\-whole\-archive "\|]" | |
155 | .RB "[\|" \-\-no\-whole\-archive "\|]" | |
156 | .RB "[\|" "\-\-wrap\ "\c | |
157 | .I symbol\c | |
158 | \&\|] | |
159 | .RB "[\|" \-X "\|]" | |
160 | .RB "[\|" \-x "\|]" | |
161 | .ad b | |
162 | .hy 1 | |
163 | .SH DESCRIPTION | |
164 | \c | |
165 | .B ld\c | |
166 | \& combines a number of object and archive files, relocates | |
167 | their data and ties up symbol references. Often the last step in | |
168 | building a new compiled program to run is a call to \c | |
169 | .B ld\c | |
170 | \&. | |
171 | ||
172 | \c | |
173 | .B ld\c | |
174 | \& accepts Linker Command Language files | |
175 | to provide explicit and total control over the linking process. | |
176 | This man page does not describe the command language; see the `\|\c | |
177 | .B ld\c | |
178 | \|' entry in `\|\c | |
179 | .B info\c | |
180 | \|', or the manual | |
181 | .I | |
182 | ld: the GNU linker | |
183 | \&, for full details on the command language and on other aspects of | |
184 | the GNU linker. | |
185 | ||
186 | This version of \c | |
187 | .B ld\c | |
188 | \& uses the general purpose BFD libraries | |
189 | to operate on object files. This allows \c | |
190 | .B ld\c | |
191 | \& to read, combine, and | |
192 | write object files in many different formats\(em\&for example, COFF or | |
193 | \c | |
194 | .B a.out\c | |
195 | \&. Different formats may be linked together to produce any | |
196 | available kind of object file. You can use `\|\c | |
197 | .B objdump \-i\c | |
198 | \|' to get a list of formats supported on various architectures; see | |
199 | .BR objdump ( 1 ). | |
200 | ||
201 | Aside from its flexibility, the GNU linker is more helpful than other | |
202 | linkers in providing diagnostic information. Many linkers abandon | |
203 | execution immediately upon encountering an error; whenever possible, | |
204 | \c | |
205 | .B ld\c | |
206 | \& continues executing, allowing you to identify other errors | |
207 | (or, in some cases, to get an output file in spite of the error). | |
208 | ||
209 | The GNU linker \c | |
210 | .B ld\c | |
211 | \& is meant to cover a broad range of situations, | |
212 | and to be as compatible as possible with other linkers. As a result, | |
213 | you have many choices to control its behavior through the command line, | |
214 | and through environment variables. | |
215 | ||
216 | .SH OPTIONS | |
217 | The plethora of command-line options may seem intimidating, but in | |
218 | actual practice few of them are used in any particular context. | |
219 | For instance, a frequent use of \c | |
220 | .B ld\c | |
221 | \& is to link standard Unix | |
222 | object files on a standard, supported Unix system. On such a system, to | |
223 | link a file \c | |
224 | .B hello.o\c | |
225 | \&: | |
226 | .sp | |
227 | .br | |
228 | $\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc | |
229 | .br | |
230 | .sp | |
231 | This tells \c | |
232 | .B ld\c | |
233 | \& to produce a file called \c | |
234 | .B output\c | |
235 | \& as the | |
236 | result of linking the file \c | |
237 | .B /lib/crt0.o\c | |
238 | \& with \c | |
239 | .B hello.o\c | |
240 | \& and | |
241 | the library \c | |
242 | .B libc.a\c | |
243 | \& which will come from the standard search | |
244 | directories. | |
245 | ||
246 | The command-line options to \c | |
247 | .B ld\c | |
248 | \& may be specified in any order, and | |
249 | may be repeated at will. For the most part, repeating an option with a | |
250 | different argument will either have no further effect, or override prior | |
251 | occurrences (those further to the left on the command line) of an | |
252 | option. | |
253 | ||
254 | The exceptions\(em\&which may meaningfully be used more than once\(em\&are | |
255 | \c | |
256 | .B \-A\c | |
257 | \&, \c | |
258 | .B \-b\c | |
259 | \& (or its synonym \c | |
260 | .B \-format\c | |
261 | \&), \c | |
262 | .B \-defsym\c | |
176355da NC |
263 | \&, \c |
264 | .B \-\-section\-start\c | |
265 | \&, \c | |
252b5132 RH |
266 | .B \-L\c |
267 | \&, \c | |
268 | .B \-l\c | |
269 | \&, \c | |
270 | .B \-R\c | |
271 | \&, and \c | |
272 | .B \-u\c | |
273 | \&. | |
274 | ||
275 | The list of object files to be linked together, shown as \c | |
276 | .I objfile\c | |
277 | \&, | |
278 | may follow, precede, or be mixed in with command-line options; save that | |
279 | an \c | |
280 | .I objfile\c | |
281 | \& argument may not be placed between an option flag and | |
282 | its argument. | |
283 | ||
284 | Usually the linker is invoked with at least one object file, but other | |
285 | forms of binary input files can also be specified with \c | |
286 | .B \-l\c | |
287 | \&, | |
288 | \c | |
289 | .B \-R\c | |
290 | \&, and the script command language. If \c | |
291 | .I no\c | |
292 | \& binary input | |
293 | files at all are specified, the linker does not produce any output, and | |
294 | issues the message `\|\c | |
295 | .B No input files\c | |
296 | \|'. | |
297 | ||
298 | Option arguments must either follow the option letter without intervening | |
299 | whitespace, or be given as separate arguments immediately following the | |
300 | option that requires them. | |
301 | ||
302 | .TP | |
303 | .BI "-A" "architecture" | |
304 | In the current release of \c | |
305 | .B ld\c | |
306 | \&, this option is useful only for the | |
307 | Intel 960 family of architectures. In that \c | |
308 | .B ld\c | |
309 | \& configuration, the | |
310 | \c | |
311 | .I architecture\c | |
312 | \& argument is one of the two-letter names identifying | |
313 | members of the 960 family; the option specifies the desired output | |
314 | target, and warns of any incompatible instructions in the input files. | |
315 | It also modifies the linker's search strategy for archive libraries, to | |
316 | support the use of libraries specific to each particular | |
317 | architecture, by including in the search loop names suffixed with the | |
318 | string identifying the architecture. | |
319 | ||
320 | For example, if your \c | |
321 | .B ld\c | |
322 | \& command line included `\|\c | |
323 | .B \-ACA\c | |
324 | \|' as | |
325 | well as `\|\c | |
326 | .B \-ltry\c | |
327 | \|', the linker would look (in its built-in search | |
328 | paths, and in any paths you specify with \c | |
329 | .B \-L\c | |
330 | \&) for a library with | |
331 | the names | |
332 | .sp | |
333 | .br | |
334 | try | |
335 | .br | |
336 | libtry.a | |
337 | .br | |
338 | tryca | |
339 | .br | |
340 | libtryca.a | |
341 | .br | |
342 | .sp | |
343 | ||
344 | The first two possibilities would be considered in any event; the last | |
345 | two are due to the use of `\|\c | |
346 | .B \-ACA\c | |
347 | \|'. | |
348 | ||
349 | Future releases of \c | |
350 | .B ld\c | |
351 | \& may support similar functionality for | |
352 | other architecture families. | |
353 | ||
354 | You can meaningfully use \c | |
355 | .B \-A\c | |
356 | \& more than once on a command line, if | |
357 | an architecture family allows combination of target architectures; each | |
358 | use will add another pair of name variants to search for when \c | |
359 | .B \-l | |
360 | specifies a library. | |
361 | ||
362 | .TP | |
363 | .BI "\-b " "input-format" | |
364 | Specify the binary format for input object files that follow this option | |
365 | on the command line. You don't usually need to specify this, as | |
366 | \c | |
367 | .B ld\c | |
368 | \& is configured to expect as a default input format the most | |
369 | usual format on each machine. \c | |
370 | .I input-format\c | |
371 | \& is a text string, the | |
372 | name of a particular format supported by the BFD libraries. | |
373 | \c | |
374 | .B \-format \c | |
375 | .I input-format\c | |
376 | \&\c | |
377 | \& has the same effect, as does the script command | |
378 | .BR TARGET . | |
379 | ||
380 | You may want to use this option if you are linking files with an unusual | |
381 | binary format. You can also use \c | |
382 | .B \-b\c | |
383 | \& to switch formats explicitly (when | |
384 | linking object files of different formats), by including | |
385 | \c | |
386 | .B \-b \c | |
387 | .I input-format\c | |
388 | \&\c | |
389 | \& before each group of object files in a | |
390 | particular format. | |
391 | ||
392 | The default format is taken from the environment variable | |
393 | .B GNUTARGET\c | |
394 | \&. You can also define the input | |
395 | format from a script, using the command \c | |
396 | .B TARGET\c | |
397 | \&. | |
398 | ||
399 | .TP | |
400 | .B \-Bstatic | |
401 | Do not link against shared libraries. This is only meaningful on | |
402 | platforms for which shared libraries are supported. | |
403 | ||
404 | .TP | |
405 | .B \-Bdynamic | |
406 | Link against dynamic libraries. This is only meaningful on platforms | |
407 | for which shared libraries are supported. This option is normally the | |
408 | default on such platforms. | |
409 | ||
a1ab1d2a UD |
410 | .TP |
411 | .B \-Bgroup | |
412 | Set the \c | |
413 | .B DF_1_GROUP | |
414 | \c | |
415 | flag in the \c | |
416 | .B DT_FLAGS_1 | |
417 | \c | |
418 | entry in the dynamic section. This causes the runtime linker to handle | |
419 | lookups in this object and its dependencies to be performed only inside | |
420 | the group. No undefined symbols are allowed. This option is only | |
421 | meaningful on ELF platforms which support shared libraries. | |
422 | ||
252b5132 RH |
423 | .TP |
424 | .B \-Bsymbolic | |
425 | When creating a shared library, bind references to global symbols to | |
426 | the definition within the shared library, if any. Normally, it is | |
427 | possible for a program linked against a shared library to override the | |
428 | definition within the shared library. This option is only meaningful | |
429 | on ELF platforms which support shared libraries. | |
430 | ||
431 | .TP | |
432 | .BI "\-c " "commandfile" | |
433 | Directs \c | |
434 | .B ld\c | |
435 | \& to read link commands from the file | |
436 | \c | |
437 | .I commandfile\c | |
438 | \&. These commands will completely override \c | |
439 | .B ld\c | |
440 | \&'s | |
441 | default link format (rather than adding to it); \c | |
442 | .I commandfile\c | |
443 | \& must | |
444 | specify everything necessary to describe the target format. | |
445 | ||
446 | ||
447 | You may also include a script of link commands directly in the command | |
448 | line by bracketing it between `\|\c | |
449 | .B {\c | |
450 | \|' and `\|\c | |
451 | .B }\c | |
452 | \|' characters. | |
453 | ||
454 | .TP | |
455 | .B \-\-cref | |
456 | Output a cross reference table. If a linker map file is being | |
457 | generated, the cross reference table is printed to the map file. | |
458 | Otherwise, it is printed on the standard output. | |
459 | ||
460 | .TP | |
461 | .B \-d | |
462 | .TP | |
463 | .B \-dc | |
464 | .TP | |
465 | .B \-dp | |
466 | These three options are equivalent; multiple forms are supported for | |
467 | compatibility with other linkers. Use any of them to make \c | |
468 | .B ld | |
469 | assign space to common symbols even if a relocatable output file is | |
470 | specified (\c | |
471 | .B \-r\c | |
472 | \&). The script command | |
473 | \c | |
474 | .B FORCE_COMMON_ALLOCATION\c | |
475 | \& has the same effect. | |
476 | ||
477 | .TP | |
176355da | 478 | .BI "-defsym " "symbol" "\fR=\fP" expression |
252b5132 RH |
479 | Create a global symbol in the output file, containing the absolute |
480 | address given by \c | |
481 | .I expression\c | |
482 | \&. You may use this option as many | |
483 | times as necessary to define multiple symbols in the command line. A | |
484 | limited form of arithmetic is supported for the \c | |
485 | .I expression\c | |
486 | \& in this | |
487 | context: you may give a hexadecimal constant or the name of an existing | |
488 | symbol, or use \c | |
489 | .B +\c | |
490 | \& and \c | |
491 | .B \-\c | |
492 | \& to add or subtract hexadecimal | |
493 | constants or symbols. If you need more elaborate expressions, consider | |
494 | using the linker command language from a script. | |
495 | ||
496 | .TP | |
497 | .B \-\-demangle | |
498 | .TP | |
499 | .B \-\-no\-demangle | |
500 | These options control whether to demangle symbol names in error | |
501 | messages and other output. When the linker is told to demangle, it | |
502 | tries to present symbol names in a readable fashion: it strips leading | |
503 | underscores if they are used by the object file format, and converts | |
504 | C++ mangled symbol names into user readable names. The linker will | |
505 | demangle by default unless the environment variable | |
506 | .B COLLECT_NO_DEMANGLE | |
507 | is set. These options may be used to override the default. | |
508 | ||
509 | .TP | |
510 | .BI "-e " "entry"\c | |
511 | \& | |
512 | Use \c | |
513 | .I entry\c | |
514 | \& as the explicit symbol for beginning execution of your | |
515 | program, rather than the default entry point. See the `\|\c | |
516 | .B ld\c | |
517 | \|' entry in `\|\c | |
518 | .B info\c | |
519 | \|' for a | |
520 | discussion of defaults and other ways of specifying the | |
521 | entry point. | |
522 | ||
523 | .TP | |
524 | .B \-embedded\-relocs | |
525 | This option is only meaningful when linking MIPS embedded PIC code, | |
526 | generated by the | |
527 | .B \-membedded\-pic | |
528 | option to the GNU compiler and assembler. It causes the linker to | |
529 | create a table which may be used at runtime to relocate any data which | |
530 | was statically initialized to pointer values. See the code in | |
531 | testsuite/ld-empic for details. | |
532 | ||
533 | .TP | |
534 | .B \-E | |
535 | .TP | |
536 | .B \-export\-dynamic | |
537 | When creating an ELF file, add all symbols to the dynamic symbol table. | |
538 | Normally, the dynamic symbol table contains only symbols which are used | |
539 | by a dynamic object. This option is needed for some uses of | |
540 | .I dlopen. | |
541 | ||
542 | .TP | |
543 | .BI "-f " "name" | |
544 | .TP | |
545 | .BI "--auxiliary " "name" | |
546 | When creating an ELF shared object, set the internal DT_AUXILIARY field | |
547 | to the specified name. This tells the dynamic linker that the symbol | |
548 | table of the shared object should be used as an auxiliary filter on the | |
549 | symbol table of the shared object | |
550 | .I name. | |
551 | ||
552 | .TP | |
553 | .BI "-F " "name" | |
554 | .TP | |
555 | .BI "--filter " "name" | |
556 | When creating an ELF shared object, set the internal DT_FILTER field to | |
557 | the specified name. This tells the dynamic linker that the symbol table | |
558 | of the shared object should be used as a filter on the symbol table of | |
559 | the shared object | |
560 | .I name. | |
561 | ||
562 | .TP | |
563 | .BI "\-format " "input\-format" | |
564 | Synonym for \c | |
565 | .B \-b\c | |
566 | \& \c | |
567 | .I input\-format\c | |
568 | \&. | |
569 | ||
570 | .TP | |
571 | .B \-g | |
572 | Accepted, but ignored; provided for compatibility with other tools. | |
573 | ||
574 | .TP | |
575 | .BI "\-G " "size"\c | |
576 | Set the maximum size of objects to be optimized using the GP register | |
577 | to | |
578 | .I size | |
579 | under MIPS ECOFF. Ignored for other object file formats. | |
580 | ||
581 | .TP | |
582 | .BI "-h " "name" | |
583 | .TP | |
584 | .BI "-soname " "name" | |
585 | When creating an ELF shared object, set the internal DT_SONAME field to | |
586 | the specified name. When an executable is linked with a shared object | |
587 | which has a DT_SONAME field, then when the executable is run the dynamic | |
588 | linker will attempt to load the shared object specified by the DT_SONAME | |
589 | field rather than the using the file name given to the linker. | |
590 | ||
591 | .TP | |
592 | .B \-\-help | |
593 | Print a summary of the command-line options on the standard output and exit. | |
594 | This option and | |
595 | .B \-\-version | |
596 | begin with two dashes instead of one | |
597 | for compatibility with other GNU programs. The other options start with | |
598 | only one dash for compatibility with other linkers. | |
599 | ||
600 | .TP | |
601 | .B \-i | |
602 | Perform an incremental link (same as option \c | |
603 | .B \-r\c | |
604 | \&). | |
605 | ||
606 | .TP | |
607 | .BI "\-l" "ar"\c | |
608 | \& | |
609 | Add an archive file \c | |
610 | .I ar\c | |
611 | \& to the list of files to link. This | |
612 | option may be used any number of times. \c | |
613 | .B ld\c | |
614 | \& will search its | |
615 | path-list for occurrences of \c | |
616 | .B lib\c | |
617 | .I ar\c | |
618 | \&.a\c | |
619 | \& for every \c | |
620 | .I ar | |
621 | specified. | |
622 | ||
623 | .TP | |
624 | .BI "\-L" "searchdir" | |
625 | This command adds path \c | |
626 | .I searchdir\c | |
627 | \& to the list of paths that | |
628 | \c | |
629 | .B ld\c | |
630 | \& will search for archive libraries. You may use this option | |
631 | any number of times. | |
632 | ||
633 | The default set of paths searched (without being specified with | |
634 | \c | |
635 | .B \-L\c | |
636 | \&) depends on what emulation mode \c | |
637 | .B ld\c | |
638 | \& is using, and in | |
639 | some cases also on how it was configured. The | |
640 | paths can also be specified in a link script with the \c | |
641 | .B SEARCH_DIR | |
642 | command. | |
643 | ||
644 | .TP | |
645 | .B \-M | |
646 | Print (to the standard output file) a link map\(em\&diagnostic information | |
647 | about where symbols are mapped by \c | |
648 | .B ld\c | |
649 | \&, and information on global | |
650 | common storage allocation. | |
651 | ||
652 | .TP | |
653 | .BI "\-Map " "mapfile"\c | |
654 | Print to the file | |
655 | .I mapfile | |
656 | a link map\(em\&diagnostic information | |
657 | about where symbols are mapped by \c | |
658 | .B ld\c | |
659 | \&, and information on global | |
660 | common storage allocation. | |
661 | ||
662 | .TP | |
663 | .BI "\-m " "emulation"\c | |
664 | Emulate the | |
665 | .I emulation | |
666 | linker. You can list the available emulations with the | |
667 | .I \-\-verbose | |
668 | or | |
669 | .I \-V | |
670 | options. This option overrides the compiled-in default, which is the | |
671 | system for which you configured | |
672 | .BR ld . | |
673 | ||
674 | .TP | |
675 | .B \-N | |
676 | specifies readable and writable \c | |
677 | .B text\c | |
678 | \& and \c | |
679 | .B data\c | |
680 | \& sections. If | |
681 | the output format supports Unix style magic numbers, the output is | |
682 | marked as \c | |
683 | .B OMAGIC\c | |
684 | \&. | |
685 | ||
686 | When you use the `\|\c | |
687 | .B \-N\c | |
688 | \&\|' option, the linker does not page-align the | |
689 | data segment. | |
690 | ||
691 | .TP | |
692 | .B \-n | |
693 | sets the text segment to be read only, and \c | |
694 | .B NMAGIC\c | |
695 | \& is written | |
696 | if possible. | |
697 | ||
698 | .TP | |
699 | .B \-noinhibit\-exec | |
700 | Normally, the linker will not produce an output file if it encounters | |
701 | errors during the link process. With this flag, you can specify that | |
702 | you wish the output file retained even after non-fatal errors. | |
703 | ||
704 | .TP | |
705 | .B \-no\-keep\-memory | |
706 | The linker normally optimizes for speed over memory usage by caching | |
707 | the symbol tables of input files in memory. This option tells the | |
708 | linker to instead optimize for memory usage, by rereading the symbol | |
709 | tables as necessary. This may be required if the linker runs out of | |
710 | memory space while linking a large executable. | |
711 | ||
712 | .TP | |
713 | .B \-no\-warn\-mismatch | |
714 | Normally the linker will give an error if you try to link together | |
715 | input files that are mismatched for some reason, perhaps because they | |
716 | have been compiled for different processors or for different | |
717 | endiannesses. This option tells the linker that it should silently | |
718 | permit such possible errors. This option should only be used with | |
719 | care, in cases when you have taken some special action that ensures | |
720 | that the linker errors are inappropriate. | |
721 | ||
722 | .TP | |
723 | .BI "\-o " "output" | |
724 | .I output\c | |
725 | \& is a name for the program produced by \c | |
726 | .B ld\c | |
727 | \&; if this | |
728 | option is not specified, the name `\|\c | |
729 | .B a.out\c | |
730 | \|' is used by default. The | |
731 | script command \c | |
732 | .B OUTPUT\c | |
733 | \& can also specify the output file name. | |
734 | ||
735 | .TP | |
736 | .BI "\-O" "level" | |
737 | Generate optimized output files. This might use significantly more | |
738 | time and therefore probably should be enabled only for generating the | |
739 | final binary. | |
740 | \c | |
741 | .I level\c | |
742 | \& is supposed to be a numeric value. Any value greater than zero enables | |
743 | the optimizations. | |
744 | ||
745 | .TP | |
0088edd2 | 746 | .BI "\--oformat " "output\-format" |
252b5132 RH |
747 | Specify the binary format for the output object file. |
748 | You don't usually need to specify this, as | |
749 | \c | |
750 | .B ld\c | |
751 | \& is configured to produce as a default output format the most | |
752 | usual format on each machine. \c | |
753 | .I output-format\c | |
754 | \& is a text string, the | |
755 | name of a particular format supported by the BFD libraries. | |
756 | The script command | |
757 | .B OUTPUT_FORMAT | |
758 | can also specify the output format, but this option overrides it. | |
759 | ||
760 | .TP | |
761 | .BI "\-R " "filename" | |
762 | Read symbol names and their addresses from \c | |
763 | .I filename\c | |
764 | \&, but do not | |
765 | relocate it or include it in the output. This allows your output file | |
766 | to refer symbolically to absolute locations of memory defined in other | |
767 | programs. | |
768 | ||
769 | .TP | |
770 | .B \-relax | |
771 | An option with machine dependent effects. Currently this option is only | |
772 | supported on the H8/300. | |
773 | ||
774 | On some platforms, use this option to perform global optimizations that | |
775 | become possible when the linker resolves addressing in your program, such | |
776 | as relaxing address modes and synthesizing new instructions in the | |
777 | output object file. | |
778 | ||
779 | On platforms where this is not supported, `\|\c | |
780 | .B \-relax\c | |
781 | \&\|' is accepted, but has no effect. | |
782 | ||
783 | .TP | |
784 | .B \-r | |
785 | Generates relocatable output\(em\&i.e., generate an output file that can in | |
786 | turn serve as input to \c | |
787 | .B ld\c | |
788 | \&. This is often called \c | |
789 | .I partial | |
790 | linking\c | |
791 | \&. As a side effect, in environments that support standard Unix | |
792 | magic numbers, this option also sets the output file's magic number to | |
793 | \c | |
794 | .B OMAGIC\c | |
795 | \&. | |
796 | If this option is not specified, an absolute file is produced. When | |
797 | linking C++ programs, this option \c | |
798 | .I will not\c | |
799 | \& resolve references to | |
800 | constructors; \c | |
801 | .B \-Ur\c | |
802 | \& is an alternative. | |
803 | ||
804 | This option does the same as \c | |
805 | .B \-i\c | |
806 | \&. | |
807 | ||
808 | .TP | |
809 | .B \-rpath\ \fIdirectory | |
810 | Add a directory to the runtime library search path. This is used when | |
811 | linking an ELF executable with shared objects. All | |
812 | .B \-rpath | |
813 | arguments are concatenated and passed to the runtime linker, which uses | |
814 | them to locate shared objects at runtime. The | |
815 | .B \-rpath | |
816 | option is also used when locating shared objects which are needed by | |
817 | shared objects explicitly included in the link; see the description of | |
818 | the | |
819 | .B \-rpath\-link | |
820 | option. If | |
821 | .B \-rpath | |
822 | is not used when linking an ELF executable, the contents of the | |
823 | environment variable | |
824 | .B LD_RUN_PATH | |
825 | will be used if it is defined. | |
826 | ||
827 | The | |
828 | .B \-rpath | |
829 | option may also be used on SunOS. By default, on SunOS, the linker | |
830 | will form a runtime search path out of all the | |
831 | .B \-L | |
832 | options it is given. If a | |
833 | .B \-rpath | |
834 | option is used, the runtime search path will be formed exclusively | |
835 | using the | |
836 | .B \-rpath | |
837 | options, ignoring | |
838 | the | |
839 | .B \-L | |
840 | options. This can be useful when using gcc, which adds many | |
841 | .B \-L | |
842 | options which may be on NFS mounted filesystems. | |
843 | ||
844 | .TP | |
845 | .B \-rpath\-link\ \fIdirectory | |
846 | When using ELF or SunOS, one shared library may require another. This | |
847 | happens when an | |
848 | .B ld\ \-shared | |
849 | link includes a shared library as one of the input files. | |
850 | ||
851 | When the linker encounters such a dependency when doing a non-shared, | |
852 | non-relocateable link, it will automatically try to locate the required | |
853 | shared library and include it in the link, if it is not included | |
854 | explicitly. In such a case, the | |
855 | .B \-rpath\-link | |
856 | option specifies the first set of directories to search. The | |
857 | .B \-rpath\-link | |
858 | option may specify a sequence of directory names either by specifying | |
859 | a list of names separated by colons, or by appearing multiple times. | |
860 | ||
861 | If the required shared library is not found, the linker will issue a | |
862 | warning and continue with the link. | |
863 | ||
864 | .TP | |
865 | .B \-S | |
866 | Omits debugger symbol information (but not all symbols) from the output file. | |
867 | ||
868 | .TP | |
869 | .B \-s | |
870 | Omits all symbol information from the output file. | |
871 | ||
872 | .TP | |
873 | .B \-shared | |
874 | Create a shared library. This is currently only supported on ELF and | |
875 | SunOS platforms (on SunOS it is not required, as the linker will | |
876 | automatically create a shared library when there are undefined symbols | |
877 | and the | |
878 | .B \-e | |
879 | option is not used). | |
880 | ||
881 | .TP | |
882 | .B \-sort\-common | |
883 | Normally, when | |
884 | .B ld | |
885 | places the global common symbols in the appropriate output sections, | |
886 | it sorts them by size. First come all the one byte symbols, then all | |
887 | the two bytes, then all the four bytes, and then everything else. | |
888 | This is to prevent gaps between symbols due to | |
889 | alignment constraints. This option disables that sorting. | |
890 | ||
891 | .TP | |
892 | .B \-split\-by\-reloc\ \fIcount | |
893 | Trys to creates extra sections in the output file so that no single | |
894 | output section in the file contains more than | |
895 | .I count | |
896 | relocations. | |
897 | This is useful when generating huge relocatable for downloading into | |
898 | certain real time kernels with the COFF object file format; since COFF | |
899 | cannot represent more than 65535 relocations in a single section. | |
900 | Note that this will fail to work with object file formats which do not | |
901 | support arbitrary sections. The linker will not split up individual | |
902 | input sections for redistribution, so if a single input section | |
903 | contains more than | |
904 | .I count | |
905 | relocations one output section will contain that many relocations. | |
906 | ||
907 | .TP | |
908 | .B \-split\-by\-file | |
909 | Similar to | |
910 | .B \-split\-by\-reloc | |
911 | but creates a new output section for each input file. | |
912 | ||
176355da NC |
913 | .TP |
914 | .BI "--section-start " "sectionname" "\fR=\fP"org | |
915 | Locate a section in the output file at the absolute | |
916 | address given by \c | |
917 | .I org\c | |
918 | \&. \c | |
919 | \c | |
920 | .I org\c | |
921 | \& must be a hexadecimal integer. | |
922 | You may use this option as many | |
923 | times as necessary to locate multiple sections in the command | |
924 | line. If you need more elaborate expressions, consider | |
925 | using the linker command language from a script. | |
926 | ||
252b5132 RH |
927 | .TP |
928 | .BI "\-Tbss " "org"\c | |
929 | .TP | |
930 | .BI "\-Tdata " "org"\c | |
931 | .TP | |
932 | .BI "\-Ttext " "org"\c | |
933 | Use \c | |
934 | .I org\c | |
935 | \& as the starting address for\(em\&respectively\(em\&the | |
936 | \c | |
937 | .B bss\c | |
938 | \&, \c | |
939 | .B data\c | |
940 | \&, or the \c | |
941 | .B text\c | |
942 | \& segment of the output file. | |
943 | \c | |
944 | .I org\c | |
945 | \& must be a hexadecimal integer. | |
946 | ||
947 | .TP | |
948 | .BI "\-T " "commandfile" | |
949 | Equivalent to \c | |
950 | .B \-c \c | |
951 | .I commandfile\c | |
952 | \&\c | |
953 | \&; supported for compatibility with | |
954 | other tools. | |
955 | ||
956 | .TP | |
957 | .B \-t | |
958 | Prints names of input files as \c | |
959 | .B ld\c | |
960 | \& processes them. | |
961 | ||
962 | .TP | |
963 | .BI "\-u " "sym" | |
964 | Forces \c | |
965 | .I sym\c | |
966 | \& to be entered in the output file as an undefined symbol. | |
967 | This may, for example, trigger linking of additional modules from | |
968 | standard libraries. \c | |
969 | .B \-u\c | |
970 | \& may be repeated with different option | |
971 | arguments to enter additional undefined symbols. | |
972 | ||
973 | .TP | |
974 | .B \-Ur | |
975 | For anything other than C++ programs, this option is equivalent to | |
976 | \c | |
977 | .B \-r\c | |
978 | \&: it generates relocatable output\(em\&i.e., an output file that can in | |
979 | turn serve as input to \c | |
980 | .B ld\c | |
981 | \&. When linking C++ programs, \c | |
982 | .B \-Ur | |
983 | .I will\c | |
984 | \& resolve references to constructors, unlike \c | |
985 | .B \-r\c | |
986 | \&. | |
987 | ||
988 | .TP | |
989 | .B \-\-verbose | |
990 | Display the version number for \c | |
991 | .B ld | |
992 | and list the supported emulations. | |
993 | Display which input files can and can not be opened. | |
994 | ||
995 | .TP | |
996 | .B \-v, \-V | |
997 | Display the version number for \c | |
998 | .B ld\c | |
999 | \&. | |
1000 | The | |
1001 | .B \-V | |
1002 | option also lists the supported emulations. | |
1003 | ||
1004 | .TP | |
1005 | .B \-\-version | |
1006 | Display the version number for \c | |
1007 | .B ld | |
1008 | and exit. | |
1009 | ||
1010 | .TP | |
1011 | .B \-warn\-common | |
1012 | Warn when a common symbol is combined with another common symbol or with | |
1013 | a symbol definition. Unix linkers allow this somewhat sloppy practice, | |
1014 | but linkers on some other operating systems do not. This option allows | |
1015 | you to find potential problems from combining global symbols. | |
1016 | ||
1017 | .TP | |
1018 | .B \-warn\-constructors | |
1019 | Warn if any global constructors are used. This is only useful for a | |
1020 | few object file formats. For formats like COFF or ELF, the linker can | |
1021 | not detect the use of global constructors. | |
1022 | ||
1023 | .TP | |
1024 | .B \-warn\-multiple\-gp | |
1025 | Warn if the output file requires multiple global-pointer values. This | |
1026 | option is only meaningful for certain processors, such as the Alpha. | |
1027 | ||
1028 | .TP | |
1029 | .B \-warn\-once | |
1030 | Only warn once for each undefined symbol, rather than once per module | |
1031 | which refers to it. | |
1032 | ||
1033 | .TP | |
1034 | .B \-warn\-section\-align | |
1035 | Warn if the address of an output section is changed because of | |
1036 | alignment. Typically, the alignment will be set by an input section. | |
1037 | The address will only be changed if it not explicitly specified; that | |
1038 | is, if the SECTIONS command does not specify a start address for the | |
1039 | section. | |
1040 | ||
1041 | .TP | |
1042 | .B \-\-whole\-archive | |
1043 | For each archive mentioned on the command line after the | |
1044 | .B \-\-whole\-archive | |
1045 | option, include every object file in the archive in the link, rather | |
1046 | than searching the archive for the required object files. This is | |
1047 | normally used to turn an archive file into a shared library, forcing | |
1048 | every object to be included in the resulting shared library. | |
1049 | ||
1050 | .TP | |
1051 | .B \-\-no\-whole\-archive | |
1052 | Turn off the effect of the | |
1053 | .B \-\-whole\-archive | |
1054 | option for archives which appear later on the command line. | |
1055 | ||
1056 | .TP | |
1057 | .BI "--wrap " "symbol" | |
1058 | Use a wrapper function for | |
1059 | .I symbol. | |
1060 | Any undefined reference to | |
1061 | .I symbol | |
1062 | will be resolved to | |
1063 | .BI "__wrap_" "symbol". | |
1064 | Any undefined reference to | |
1065 | .BI "__real_" "symbol" | |
1066 | will be resolved to | |
1067 | .I symbol. | |
1068 | ||
1069 | .TP | |
1070 | .B \-X | |
1071 | Delete all temporary local symbols. For most targets, this is all local | |
1072 | symbols whose names begin with `\|\c | |
1073 | .B L\c | |
1074 | \|'. | |
1075 | ||
1076 | .TP | |
1077 | .B \-x | |
1078 | Delete all local symbols. | |
1079 | ||
1080 | .PP | |
1081 | ||
1082 | .SH ENVIRONMENT | |
1083 | \c | |
1084 | You can change the behavior of | |
1085 | .B ld\c | |
1086 | \& with the environment variable \c | |
1087 | .B GNUTARGET\c | |
1088 | \&. | |
1089 | ||
1090 | \c | |
1091 | .B GNUTARGET\c | |
1092 | \& determines the input-file object format if you don't | |
1093 | use \c | |
1094 | .B \-b\c | |
1095 | \& (or its synonym \c | |
1096 | .B \-format\c | |
1097 | \&). Its value should be one | |
1098 | of the BFD names for an input format. If there is no | |
1099 | \c | |
1100 | .B GNUTARGET\c | |
1101 | \& in the environment, \c | |
1102 | .B ld\c | |
1103 | \& uses the natural format | |
1104 | of the host. If \c | |
1105 | .B GNUTARGET\c | |
1106 | \& is set to \c | |
1107 | .B default\c | |
1108 | \& then BFD attempts to discover the | |
1109 | input format by examining binary input files; this method often | |
1110 | succeeds, but there are potential ambiguities, since there is no method | |
1111 | of ensuring that the magic number used to flag object-file formats is | |
1112 | unique. However, the configuration procedure for BFD on each system | |
1113 | places the conventional format for that system first in the search-list, | |
1114 | so ambiguities are resolved in favor of convention. | |
1115 | ||
1116 | .PP | |
1117 | ||
1118 | .SH "SEE ALSO" | |
1119 | ||
1120 | .BR objdump ( 1 ) | |
1121 | .br | |
1122 | .br | |
1123 | .RB "`\|" ld "\|' and `\|" binutils "\|'" | |
1124 | entries in | |
1125 | .B info\c | |
1126 | .br | |
1127 | .I | |
1128 | ld: the GNU linker\c | |
1129 | , Steve Chamberlain and Roland Pesch; | |
1130 | .I | |
1131 | The GNU Binary Utilities\c | |
1132 | , Roland H. Pesch. | |
1133 | ||
1134 | .SH COPYING | |
cf055d54 NC |
1135 | Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 1998, 2000 Free Software Foundation, Inc. |
1136 | .PP | |
1137 | This document is distributed under the terms of the GNU Free | |
e47b9e39 NC |
1138 | Documentation License, version 1.1. That license is described in the |
1139 | sources for this manual page, but it is not displayed here in order to | |
1140 | make this manual more consise. Copies of this license can also be | |
1141 | obtained from: http://www.gnu.org/copyleft/. | |
cf055d54 | 1142 | |
e47b9e39 NC |
1143 | \" .SH GNU Free Documentation License |
1144 | \" Version 1.1, March 2000 | |
cf055d54 | 1145 | |
e47b9e39 NC |
1146 | \" Copyright (C) 2000 Free Software Foundation, Inc. |
1147 | \" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
cf055d54 | 1148 | |
e47b9e39 NC |
1149 | \" Everyone is permitted to copy and distribute verbatim |
1150 | \" copies of this license document, but changing it is | |
1151 | \" not allowed. | |
1152 | \" .PP | |
1153 | \" 0. PREAMBLE | |
1154 | \" .PP | |
1155 | \" The purpose of this License is to make a manual, textbook, or other | |
1156 | \" written document "free" in the sense of freedom: to assure everyone | |
1157 | \" the effective freedom to copy and redistribute it, with or without | |
1158 | \" modifying it, either commercially or noncommercially. Secondarily, | |
1159 | \" this License preserves for the author and publisher a way to get | |
1160 | \" credit for their work, while not being considered responsible for | |
1161 | \" modifications made by others. | |
1162 | \" .PP | |
1163 | \" This License is a kind of "copyleft", which means that derivative | |
1164 | \" works of the document must themselves be free in the same sense. It | |
1165 | \" complements the GNU General Public License, which is a copyleft | |
1166 | \" license designed for free software. | |
1167 | \" .PP | |
1168 | \" We have designed this License in order to use it for manuals for free | |
1169 | \" software, because free software needs free documentation: a free | |
1170 | \" program should come with manuals providing the same freedoms that the | |
1171 | \" software does. But this License is not limited to software manuals; | |
1172 | \" it can be used for any textual work, regardless of subject matter or | |
1173 | \" whether it is published as a printed book. We recommend this License | |
1174 | \" principally for works whose purpose is instruction or reference. | |
1175 | \" .PP | |
1176 | \" 1. APPLICABILITY AND DEFINITIONS | |
1177 | \" .PP | |
1178 | \" This License applies to any manual or other work that contains a | |
1179 | \" notice placed by the copyright holder saying it can be distributed | |
1180 | \" under the terms of this License. The "Document", below, refers to any | |
1181 | \" such manual or work. Any member of the public is a licensee, and is | |
1182 | \" addressed as "you". | |
1183 | \" .PP | |
1184 | \" A "Modified Version" of the Document means any work containing the | |
1185 | \" Document or a portion of it, either copied verbatim, or with | |
1186 | \" modifications and/or translated into another language. | |
1187 | \" .PP | |
1188 | \" A "Secondary Section" is a named appendix or a front-matter section of | |
1189 | \" the Document that deals exclusively with the relationship of the | |
1190 | \" publishers or authors of the Document to the Document's overall subject | |
1191 | \" (or to related matters) and contains nothing that could fall directly | |
1192 | \" within that overall subject. (For example, if the Document is in part a | |
1193 | \" textbook of mathematics, a Secondary Section may not explain any | |
1194 | \" mathematics.) The relationship could be a matter of historical | |
1195 | \" connection with the subject or with related matters, or of legal, | |
1196 | \" commercial, philosophical, ethical or political position regarding | |
1197 | \" them. | |
1198 | \" .PP | |
1199 | \" The "Invariant Sections" are certain Secondary Sections whose titles | |
1200 | \" are designated, as being those of Invariant Sections, in the notice | |
1201 | \" that says that the Document is released under this License. | |
1202 | \" .PP | |
1203 | \" The "Cover Texts" are certain short passages of text that are listed, | |
1204 | \" as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
1205 | \" the Document is released under this License. | |
1206 | \" .PP | |
1207 | \" A "Transparent" copy of the Document means a machine-readable copy, | |
1208 | \" represented in a format whose specification is available to the | |
1209 | \" general public, whose contents can be viewed and edited directly and | |
1210 | \" straightforwardly with generic text editors or (for images composed of | |
1211 | \" pixels) generic paint programs or (for drawings) some widely available | |
1212 | \" drawing editor, and that is suitable for input to text formatters or | |
1213 | \" for automatic translation to a variety of formats suitable for input | |
1214 | \" to text formatters. A copy made in an otherwise Transparent file | |
1215 | \" format whose markup has been designed to thwart or discourage | |
1216 | \" subsequent modification by readers is not Transparent. A copy that is | |
1217 | \" not "Transparent" is called "Opaque". | |
1218 | \" .PP | |
1219 | \" Examples of suitable formats for Transparent copies include plain | |
1220 | \" ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
1221 | \" or XML using a publicly available DTD, and standard-conforming simple | |
1222 | \" HTML designed for human modification. Opaque formats include | |
1223 | \" PostScript, PDF, proprietary formats that can be read and edited only | |
1224 | \" by proprietary word processors, SGML or XML for which the DTD and/or | |
1225 | \" processing tools are not generally available, and the | |
1226 | \" machine-generated HTML produced by some word processors for output | |
1227 | \" purposes only. | |
1228 | \" .PP | |
1229 | \" The "Title Page" means, for a printed book, the title page itself, | |
1230 | \" plus such following pages as are needed to hold, legibly, the material | |
1231 | \" this License requires to appear in the title page. For works in | |
1232 | \" formats which do not have any title page as such, "Title Page" means | |
1233 | \" the text near the most prominent appearance of the work's title, | |
1234 | \" preceding the beginning of the body of the text. | |
1235 | \" .PP | |
1236 | \" 2. VERBATIM COPYING | |
1237 | \" .PP | |
1238 | \" You may copy and distribute the Document in any medium, either | |
1239 | \" commercially or noncommercially, provided that this License, the | |
1240 | \" copyright notices, and the license notice saying this License applies | |
1241 | \" to the Document are reproduced in all copies, and that you add no other | |
1242 | \" conditions whatsoever to those of this License. You may not use | |
1243 | \" technical measures to obstruct or control the reading or further | |
1244 | \" copying of the copies you make or distribute. However, you may accept | |
1245 | \" compensation in exchange for copies. If you distribute a large enough | |
1246 | \" number of copies you must also follow the conditions in section 3. | |
1247 | \" .PP | |
1248 | \" You may also lend copies, under the same conditions stated above, and | |
1249 | \" you may publicly display copies. | |
1250 | \" .PP | |
1251 | \" 3. COPYING IN QUANTITY | |
1252 | \" .PP | |
1253 | \" If you publish printed copies of the Document numbering more than 100, | |
1254 | \" and the Document's license notice requires Cover Texts, you must enclose | |
1255 | \" the copies in covers that carry, clearly and legibly, all these Cover | |
1256 | \" Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
1257 | \" the back cover. Both covers must also clearly and legibly identify | |
1258 | \" you as the publisher of these copies. The front cover must present | |
1259 | \" the full title with all words of the title equally prominent and | |
1260 | \" visible. You may add other material on the covers in addition. | |
1261 | \" Copying with changes limited to the covers, as long as they preserve | |
1262 | \" the title of the Document and satisfy these conditions, can be treated | |
1263 | \" as verbatim copying in other respects. | |
1264 | \" .PP | |
1265 | \" If the required texts for either cover are too voluminous to fit | |
1266 | \" legibly, you should put the first ones listed (as many as fit | |
1267 | \" reasonably) on the actual cover, and continue the rest onto adjacent | |
1268 | \" pages. | |
1269 | \" .PP | |
1270 | \" If you publish or distribute Opaque copies of the Document numbering | |
1271 | \" more than 100, you must either include a machine-readable Transparent | |
1272 | \" copy along with each Opaque copy, or state in or with each Opaque copy | |
1273 | \" a publicly-accessible computer-network location containing a complete | |
1274 | \" Transparent copy of the Document, free of added material, which the | |
1275 | \" general network-using public has access to download anonymously at no | |
1276 | \" charge using public-standard network protocols. If you use the latter | |
1277 | \" option, you must take reasonably prudent steps, when you begin | |
1278 | \" distribution of Opaque copies in quantity, to ensure that this | |
1279 | \" Transparent copy will remain thus accessible at the stated location | |
1280 | \" until at least one year after the last time you distribute an Opaque | |
1281 | \" copy (directly or through your agents or retailers) of that edition to | |
1282 | \" the public. | |
1283 | \" .PP | |
1284 | \" It is requested, but not required, that you contact the authors of the | |
1285 | \" Document well before redistributing any large number of copies, to give | |
1286 | \" them a chance to provide you with an updated version of the Document. | |
1287 | \" .PP | |
1288 | \" 4. MODIFICATIONS | |
1289 | \" .PP | |
1290 | \" You may copy and distribute a Modified Version of the Document under | |
1291 | \" the conditions of sections 2 and 3 above, provided that you release | |
1292 | \" the Modified Version under precisely this License, with the Modified | |
1293 | \" Version filling the role of the Document, thus licensing distribution | |
1294 | \" and modification of the Modified Version to whoever possesses a copy | |
1295 | \" of it. In addition, you must do these things in the Modified Version: | |
1296 | \" .PP | |
1297 | \" A. Use in the Title Page (and on the covers, if any) a title distinct | |
1298 | \" from that of the Document, and from those of previous versions | |
1299 | \" (which should, if there were any, be listed in the History section | |
1300 | \" of the Document). You may use the same title as a previous version | |
1301 | \" if the original publisher of that version gives permission. | |
1302 | \" .PP | |
1303 | \" B. List on the Title Page, as authors, one or more persons or entities | |
1304 | \" responsible for authorship of the modifications in the Modified | |
1305 | \" Version, together with at least five of the principal authors of the | |
1306 | \" Document (all of its principal authors, if it has less than five). | |
1307 | \" .PP | |
1308 | \" C. State on the Title page the name of the publisher of the | |
1309 | \" Modified Version, as the publisher. | |
1310 | \" .PP | |
1311 | \" D. Preserve all the copyright notices of the Document. | |
1312 | \" .PP | |
1313 | \" E. Add an appropriate copyright notice for your modifications | |
1314 | \" adjacent to the other copyright notices. | |
1315 | \" .PP | |
1316 | \" F. Include, immediately after the copyright notices, a license notice | |
1317 | \" giving the public permission to use the Modified Version under the | |
1318 | \" terms of this License, in the form shown in the Addendum below. | |
1319 | \" Preserve in that license notice the full lists of Invariant Sections | |
1320 | \" and required Cover Texts given in the Document's license notice. | |
1321 | \" .PP | |
1322 | \" H. Include an unaltered copy of this License. | |
1323 | \" .PP | |
1324 | \" I. Preserve the section entitled "History", and its title, and add to | |
1325 | \" it an item stating at least the title, year, new authors, and | |
1326 | \" publisher of the Modified Version as given on the Title Page. If | |
1327 | \" there is no section entitled "History" in the Document, create one | |
1328 | \" stating the title, year, authors, and publisher of the Document as | |
1329 | \" given on its Title Page, then add an item describing the Modified | |
1330 | \" Version as stated in the previous sentence. | |
1331 | \" .PP | |
1332 | \" J. Preserve the network location, if any, given in the Document for | |
1333 | \" public access to a Transparent copy of the Document, and likewise | |
1334 | \" the network locations given in the Document for previous versions | |
1335 | \" it was based on. These may be placed in the "History" section. | |
1336 | \" You may omit a network location for a work that was published at | |
1337 | \" least four years before the Document itself, or if the original | |
1338 | \" publisher of the version it refers to gives permission. | |
1339 | \" .PP | |
1340 | \" K. In any section entitled "Acknowledgements" or "Dedications", | |
1341 | \" preserve the section's title, and preserve in the section all the | |
1342 | \" substance and tone of each of the contributor acknowledgements | |
1343 | \" and/or dedications given therein. | |
1344 | \" .PP | |
1345 | \" L. Preserve all the Invariant Sections of the Document, | |
1346 | \" unaltered in their text and in their titles. Section numbers | |
1347 | \" or the equivalent are not considered part of the section titles. | |
1348 | \" .PP | |
1349 | \" M. Delete any section entitled "Endorsements". Such a section | |
1350 | \" may not be included in the Modified Version. | |
1351 | \" .PP | |
1352 | \" N. Do not retitle any existing section as "Endorsements" | |
1353 | \" or to conflict in title with any Invariant Section. | |
1354 | \" .PP | |
1355 | \" If the Modified Version includes new front-matter sections or | |
1356 | \" appendices that qualify as Secondary Sections and contain no material | |
1357 | \" copied from the Document, you may at your option designate some or all | |
1358 | \" of these sections as invariant. To do this, add their titles to the | |
1359 | \" list of Invariant Sections in the Modified Version's license notice. | |
1360 | \" These titles must be distinct from any other section titles. | |
1361 | \" .PP | |
1362 | \" You may add a section entitled "Endorsements", provided it contains | |
1363 | \" nothing but endorsements of your Modified Version by various | |
1364 | \" parties--for example, statements of peer review or that the text has | |
1365 | \" been approved by an organization as the authoritative definition of a | |
1366 | \" standard. | |
1367 | \" .PP | |
1368 | \" You may add a passage of up to five words as a Front-Cover Text, and a | |
1369 | \" passage of up to 25 words as a Back-Cover Text, to the end of the list | |
1370 | \" of Cover Texts in the Modified Version. Only one passage of | |
1371 | \" Front-Cover Text and one of Back-Cover Text may be added by (or | |
1372 | \" through arrangements made by) any one entity. If the Document already | |
1373 | \" includes a cover text for the same cover, previously added by you or | |
1374 | \" by arrangement made by the same entity you are acting on behalf of, | |
1375 | \" you may not add another; but you may replace the old one, on explicit | |
1376 | \" permission from the previous publisher that added the old one. | |
1377 | \" .PP | |
1378 | \" The author(s) and publisher(s) of the Document do not by this License | |
1379 | \" give permission to use their names for publicity for or to assert or | |
1380 | \" imply endorsement of any Modified Version. | |
1381 | \" .PP | |
1382 | ||
1383 | \" 5. COMBINING DOCUMENTS | |
1384 | \" .PP | |
1385 | \" You may combine the Document with other documents released under this | |
1386 | \" License, under the terms defined in section 4 above for modified | |
1387 | \" versions, provided that you include in the combination all of the | |
1388 | \" Invariant Sections of all of the original documents, unmodified, and | |
1389 | \" list them all as Invariant Sections of your combined work in its | |
1390 | \" license notice. | |
1391 | \" .PP | |
1392 | \" The combined work need only contain one copy of this License, and | |
1393 | \" multiple identical Invariant Sections may be replaced with a single | |
1394 | \" copy. If there are multiple Invariant Sections with the same name but | |
1395 | \" different contents, make the title of each such section unique by | |
1396 | \" adding at the end of it, in parentheses, the name of the original | |
1397 | \" author or publisher of that section if known, or else a unique number. | |
1398 | \" Make the same adjustment to the section titles in the list of | |
1399 | \" Invariant Sections in the license notice of the combined work. | |
1400 | \" .PP | |
1401 | \" In the combination, you must combine any sections entitled "History" | |
1402 | \" in the various original documents, forming one section entitled | |
1403 | \" "History"; likewise combine any sections entitled "Acknowledgements", | |
1404 | \" and any sections entitled "Dedications". You must delete all sections | |
1405 | \" entitled "Endorsements." | |
1406 | \" .PP | |
1407 | ||
1408 | \" 6. COLLECTIONS OF DOCUMENTS | |
1409 | \" .PP | |
1410 | \" You may make a collection consisting of the Document and other documents | |
1411 | \" released under this License, and replace the individual copies of this | |
1412 | \" License in the various documents with a single copy that is included in | |
1413 | \" the collection, provided that you follow the rules of this License for | |
1414 | \" verbatim copying of each of the documents in all other respects. | |
1415 | \" .PP | |
1416 | \" You may extract a single document from such a collection, and distribute | |
1417 | \" it individually under this License, provided you insert a copy of this | |
1418 | \" License into the extracted document, and follow this License in all | |
1419 | \" other respects regarding verbatim copying of that document. | |
1420 | \" .PP | |
1421 | ||
1422 | \" 7. AGGREGATION WITH INDEPENDENT WORKS | |
1423 | \" .PP | |
1424 | \" A compilation of the Document or its derivatives with other separate | |
1425 | \" and independent documents or works, in or on a volume of a storage or | |
1426 | \" distribution medium, does not as a whole count as a Modified Version | |
1427 | \" of the Document, provided no compilation copyright is claimed for the | |
1428 | \" compilation. Such a compilation is called an "aggregate", and this | |
1429 | \" License does not apply to the other self-contained works thus compiled | |
1430 | \" with the Document, on account of their being thus compiled, if they | |
1431 | \" are not themselves derivative works of the Document. | |
1432 | \" .PP | |
1433 | \" If the Cover Text requirement of section 3 is applicable to these | |
1434 | \" copies of the Document, then if the Document is less than one quarter | |
1435 | \" of the entire aggregate, the Document's Cover Texts may be placed on | |
1436 | \" covers that surround only the Document within the aggregate. | |
1437 | \" Otherwise they must appear on covers around the whole aggregate. | |
1438 | \" .PP | |
1439 | ||
1440 | \" 8. TRANSLATION | |
1441 | \" .PP | |
1442 | \" Translation is considered a kind of modification, so you may | |
1443 | \" distribute translations of the Document under the terms of section 4. | |
1444 | \" Replacing Invariant Sections with translations requires special | |
1445 | \" permission from their copyright holders, but you may include | |
1446 | \" translations of some or all Invariant Sections in addition to the | |
1447 | \" original versions of these Invariant Sections. You may include a | |
1448 | \" translation of this License provided that you also include the | |
1449 | \" original English version of this License. In case of a disagreement | |
1450 | \" between the translation and the original English version of this | |
1451 | \" License, the original English version will prevail. | |
1452 | \" .PP | |
1453 | ||
1454 | \" 9. TERMINATION | |
1455 | \" .PP | |
1456 | \" You may not copy, modify, sublicense, or distribute the Document except | |
1457 | \" as expressly provided for under this License. Any other attempt to | |
1458 | \" copy, modify, sublicense or distribute the Document is void, and will | |
1459 | \" automatically terminate your rights under this License. However, | |
1460 | \" parties who have received copies, or rights, from you under this | |
1461 | \" License will not have their licenses terminated so long as such | |
1462 | \" parties remain in full compliance. | |
1463 | \" .PP | |
1464 | ||
1465 | \" 10. FUTURE REVISIONS OF THIS LICENSE | |
1466 | \" .PP | |
1467 | \" The Free Software Foundation may publish new, revised versions | |
1468 | \" of the GNU Free Documentation License from time to time. Such new | |
1469 | \" versions will be similar in spirit to the present version, but may | |
1470 | \" differ in detail to address new problems or concerns. See | |
1471 | \" http://www.gnu.org/copyleft/. | |
1472 | \" .PP | |
1473 | \" Each version of the License is given a distinguishing version number. | |
1474 | \" If the Document specifies that a particular numbered version of this | |
1475 | \" License "or any later version" applies to it, you have the option of | |
1476 | \" following the terms and conditions either of that specified version or | |
1477 | \" of any later version that has been published (not as a draft) by the | |
1478 | \" Free Software Foundation. If the Document does not specify a version | |
1479 | \" number of this License, you may choose any version ever published (not | |
1480 | \" as a draft) by the Free Software Foundation. | |
1481 | \" .PP | |
1482 | ||
1483 | \" ADDENDUM: How to use this License for your documents | |
1484 | \" .PP | |
1485 | \" To use this License in a document you have written, include a copy of | |
1486 | \" the License in the document and put the following copyright and | |
1487 | \" license notices just after the title page: | |
1488 | \" .PP | |
1489 | \" Copyright (c) YEAR YOUR NAME. | |
1490 | \" Permission is granted to copy, distribute and/or | |
1491 | \" modify this document under the terms of the GNU | |
1492 | \" Free Documentation License, Version 1.1 or any later | |
1493 | \" version published by the Free Software Foundation; | |
1494 | \" with the Invariant Sections being LIST THEIR TITLES, | |
1495 | \" with the Front-Cover Texts being LIST, and with the | |
1496 | \" Back-Cover Texts being LIST. A copy of the license | |
1497 | \" is included in the section entitled "GNU Free | |
1498 | \" Documentation License". | |
1499 | \" .PP | |
1500 | \" If you have no Invariant Sections, write "with no Invariant Sections" | |
1501 | \" instead of saying which ones are invariant. If you have no | |
1502 | \" Front-Cover Texts, write "no Front-Cover Texts" instead of | |
1503 | \" "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. | |
1504 | \" .PP | |
1505 | \" If your document contains nontrivial examples of program code, we | |
1506 | \" recommend releasing these examples in parallel under your choice of | |
1507 | \" free software license, such as the GNU General Public License, | |
1508 | \" to permit their use in free software. |