Commit | Line | Data |
---|---|---|
8c2bc687 NC |
1 | .\" Copyright 1991, 1992, 1993, 1995, 1998, 1999, 2000 |
2 | .\" Free Software Foundation, Inc. | |
252b5132 | 3 | .\" See section COPYING for conditions for redistribution |
cf055d54 | 4 | .TH ar 1 "1999" "Free Software Foundation" "GNU Development Tools" |
252b5132 RH |
5 | .de BP |
6 | .sp | |
7 | .ti \-.2i | |
8 | \(** | |
9 | .. | |
10 | ||
11 | .SH NAME | |
12 | ar \- create, modify, and extract from archives. | |
13 | ||
14 | .SH SYNOPSIS | |
15 | .hy 0 | |
16 | .na | |
17 | .BR ar " [\|" "-" "\|]"\c | |
3de39064 | 18 | .I {dmpqrtx}[abcfilNoPsSuvV] \c |
252b5132 RH |
19 | [\|\c |
20 | .I membername\c | |
21 | \&\|] \c | |
3de39064 ILT |
22 | [\|\c |
23 | .I count\c | |
24 | \&\|] \c | |
252b5132 RH |
25 | .I archive\c |
26 | \& \c | |
27 | .I files\c | |
28 | \&.\|.\|. | |
29 | ||
30 | .ad b | |
31 | .hy 1 | |
32 | .SH DESCRIPTION | |
33 | The GNU \c | |
34 | .B ar\c | |
35 | \& program creates, modifies, and extracts from | |
36 | archives. An \c | |
37 | .I archive\c | |
38 | \& is a single file holding a collection of | |
39 | other files in a structure that makes it possible to retrieve | |
40 | the original individual files (called \c | |
41 | .I members\c | |
42 | \& of the archive). | |
43 | ||
44 | The original files' contents, mode (permissions), timestamp, owner, and | |
45 | group are preserved in the archive, and may be reconstituted on | |
46 | extraction. | |
47 | ||
48 | GNU \c | |
49 | .B ar\c | |
50 | \& can maintain archives whose members have names of any | |
51 | length; however, depending on how \c | |
52 | .B ar\c | |
53 | \& is configured on your | |
54 | system, a limit on member-name length may be imposed (for compatibility | |
55 | with archive formats maintained with other tools). If it exists, the | |
56 | limit is often 15 characters (typical of formats related to a.out) or 16 | |
57 | characters (typical of formats related to coff). | |
58 | ||
59 | \c | |
60 | .B ar\c | |
61 | \& is considered a binary utility because archives of this sort | |
62 | are most often used as \c | |
63 | .I libraries\c | |
64 | \& holding commonly needed | |
65 | subroutines. | |
66 | ||
67 | \c | |
68 | .B ar\c | |
69 | \& will create an index to the symbols defined in relocatable | |
70 | object modules in the archive when you specify the modifier `\|\c | |
71 | .B s\c | |
72 | \|'. | |
73 | Once created, this index is updated in the archive whenever \c | |
74 | .B ar\c | |
75 | \& | |
76 | makes a change to its contents (save for the `\|\c | |
77 | .B q\c | |
78 | \|' update operation). | |
79 | An archive with such an index speeds up linking to the library, and | |
80 | allows routines in the library to call each other without regard to | |
81 | their placement in the archive. | |
82 | ||
83 | You may use `\|\c | |
84 | .B nm \-s\c | |
85 | \|' or `\|\c | |
86 | .B nm \-\-print\-armap\c | |
87 | \|' to list this index | |
88 | table. If an archive lacks the table, another form of \c | |
89 | .B ar\c | |
90 | \& called | |
91 | \c | |
92 | .B ranlib\c | |
93 | \& can be used to add just the table. | |
94 | ||
95 | \c | |
96 | .B ar\c | |
97 | \& insists on at least two arguments to execute: one | |
98 | keyletter specifying the \c | |
99 | .I operation\c | |
100 | \& (optionally accompanied by other | |
101 | keyletters specifying \c | |
102 | .I modifiers\c | |
103 | \&), and the archive name to act on. | |
104 | ||
105 | Most operations can also accept further \c | |
106 | .I files\c | |
107 | \& arguments, | |
108 | specifying particular files to operate on. | |
109 | ||
110 | .SH OPTIONS | |
111 | GNU \c | |
112 | .B ar\c | |
113 | \& allows you to mix the operation code \c | |
114 | .I p\c | |
115 | \& and modifier | |
116 | flags \c | |
117 | .I mod\c | |
118 | \& in any order, within the first command-line argument. | |
119 | ||
120 | If you wish, you may begin the first command-line argument with a | |
121 | dash. | |
122 | ||
123 | The \c | |
124 | .I p\c | |
125 | \& keyletter specifies what operation to execute; it may be | |
126 | any of the following, but you must specify only one of them: | |
127 | ||
128 | .TP | |
129 | .B d | |
130 | \c | |
131 | .I Delete\c | |
132 | \& modules from the archive. Specify the names of modules to | |
133 | be deleted as \c | |
134 | .I files\c | |
135 | \&; the archive is untouched if you | |
136 | specify no files to delete. | |
137 | ||
138 | If you specify the `\|\c | |
139 | .B v\c | |
140 | \|' modifier, \c | |
141 | .B ar\c | |
142 | \& will list each module | |
143 | as it is deleted. | |
144 | ||
145 | .TP | |
146 | .B m | |
147 | Use this operation to \c | |
148 | .I move\c | |
149 | \& members in an archive. | |
150 | ||
151 | The ordering of members in an archive can make a difference in how | |
152 | programs are linked using the library, if a symbol is defined in more | |
153 | than one member. | |
154 | ||
155 | If no modifiers are used with \c | |
156 | .B m\c | |
157 | \&, any members you name in the | |
158 | \c | |
159 | .I files\c | |
160 | \& arguments are moved to the \c | |
161 | .I end\c | |
162 | \& of the archive; | |
163 | you can use the `\|\c | |
164 | .B a\c | |
165 | \|', `\|\c | |
166 | .B b\c | |
167 | \|', or `\|\c | |
168 | .B i\c | |
169 | \|' modifiers to move them to a | |
170 | specified place instead. | |
171 | ||
172 | .TP | |
173 | .B p | |
174 | \c | |
175 | .I Print\c | |
176 | \& the specified members of the archive, to the standard | |
177 | output file. If the `\|\c | |
178 | .B v\c | |
179 | \|' modifier is specified, show the member | |
180 | name before copying its contents to standard output. | |
181 | ||
182 | If you specify no \c | |
183 | .I files\c | |
184 | \&, all the files in the archive are printed. | |
185 | ||
186 | .TP | |
187 | .B q | |
188 | \c | |
189 | .I Quick append\c | |
190 | \&; add \c | |
191 | .I files\c | |
192 | \& to the end of \c | |
193 | .I archive\c | |
194 | \&, | |
195 | without checking for replacement. | |
196 | ||
197 | The modifiers `\|\c | |
198 | .B a\c | |
199 | \|', `\|\c | |
200 | .B b\c | |
201 | \|', and `\|\c | |
202 | .B i\c | |
203 | \|' do \c | |
204 | .I not\c | |
205 | \& affect this | |
206 | operation; new members are always placed at the end of the archive. | |
207 | ||
208 | The modifier `\|\c | |
209 | .B v\c | |
210 | \|' makes \c | |
211 | .B ar\c | |
212 | \& list each file as it is appended. | |
213 | ||
214 | Since the point of this operation is speed, the archive's symbol table | |
215 | index is not updated, even if it already existed; you can use `\|\c | |
216 | .B ar s\c | |
217 | \|' or | |
218 | \c | |
219 | .B ranlib\c | |
220 | \& explicitly to update the symbol table index. | |
221 | ||
222 | However, too many different systems assume quick append rebuilds the | |
223 | index, so GNU | |
224 | .B ar | |
225 | implements `\|\c | |
226 | .B q\c | |
227 | \|' as a synonym for `\|\c | |
228 | .B r\c | |
229 | \|'. | |
230 | ||
231 | .TP | |
232 | .B r | |
233 | Insert \c | |
234 | .I files\c | |
235 | \& into \c | |
236 | .I archive\c | |
237 | \& (with \c | |
238 | .I replacement\c | |
239 | \&). This | |
240 | operation differs from `\|\c | |
241 | .B q\c | |
242 | \|' in that any previously existing members | |
243 | are deleted if their names match those being added. | |
244 | ||
245 | If one of the files named in \c | |
246 | .I files\c | |
247 | \& doesn't exist, \c | |
248 | .B ar\c | |
249 | \& | |
250 | displays an error message, and leaves undisturbed any existing members | |
251 | of the archive matching that name. | |
252 | ||
253 | By default, new members are added at the end of the file; but you may | |
254 | use one of the modifiers `\|\c | |
255 | .B a\c | |
256 | \|', `\|\c | |
257 | .B b\c | |
258 | \|', or `\|\c | |
259 | .B i\c | |
260 | \|' to request | |
261 | placement relative to some existing member. | |
262 | ||
263 | The modifier `\|\c | |
264 | .B v\c | |
265 | \|' used with this operation elicits a line of | |
266 | output for each file inserted, along with one of the letters `\|\c | |
267 | .B a\c | |
268 | \|' or | |
269 | `\|\c | |
270 | .B r\c | |
271 | \|' to indicate whether the file was appended (no old member | |
272 | deleted) or replaced. | |
273 | ||
274 | .TP | |
275 | .B t | |
276 | Display a \c | |
277 | .I table\c | |
278 | \& listing the contents of \c | |
279 | .I archive\c | |
280 | \&, or those | |
281 | of the files listed in \c | |
282 | .I files\c | |
283 | \& that are present in the | |
284 | archive. Normally only the member name is shown; if you also want to | |
285 | see the modes (permissions), timestamp, owner, group, and size, you can | |
286 | request that by also specifying the `\|\c | |
287 | .B v\c | |
288 | \|' modifier. | |
289 | ||
290 | If you do not specify any \c | |
291 | .I files\c | |
292 | \&, all files in the archive | |
293 | are listed. | |
294 | ||
295 | If there is more than one file with the same name (say, `\|\c | |
296 | .B fie\c | |
297 | \|') in | |
298 | an archive (say `\|\c | |
299 | .B b.a\c | |
300 | \|'), `\|\c | |
301 | .B ar t b.a fie\c | |
302 | \|' will list only the | |
303 | first instance; to see them all, you must ask for a complete | |
304 | listing\(em\&in our example, `\|\c | |
305 | .B ar t b.a\c | |
306 | \|'. | |
307 | ||
308 | .TP | |
309 | .B x | |
310 | \c | |
311 | .I Extract\c | |
312 | \& members (named \c | |
313 | .I files\c | |
314 | \&) from the archive. You can | |
315 | use the `\|\c | |
316 | .B v\c | |
317 | \|' modifier with this operation, to request that | |
318 | \c | |
319 | .B ar\c | |
320 | \& list each name as it extracts it. | |
321 | ||
322 | If you do not specify any \c | |
323 | .I files\c | |
324 | \&, all files in the archive | |
325 | are extracted. | |
326 | ||
327 | .PP | |
328 | ||
329 | A number of modifiers (\c | |
330 | .I mod\c | |
331 | \&) may immediately follow the \c | |
332 | .I p\c | |
333 | \& | |
334 | keyletter, to specify variations on an operation's behavior: | |
335 | ||
336 | .TP | |
337 | .B a | |
338 | Add new files \c | |
339 | .I after\c | |
340 | \& an existing member of the | |
341 | archive. If you use the modifier \c | |
342 | .B a\c | |
343 | \&, the name of an existing archive | |
344 | member must be present as the \c | |
345 | .I membername\c | |
346 | \& argument, before the | |
347 | \c | |
348 | .I archive\c | |
349 | \& specification. | |
350 | ||
351 | .TP | |
352 | .B b | |
353 | Add new files \c | |
354 | .I before\c | |
355 | \& an existing member of the | |
356 | archive. If you use the modifier \c | |
357 | .B b\c | |
358 | \&, the name of an existing archive | |
359 | member must be present as the \c | |
360 | .I membername\c | |
361 | \& argument, before the | |
362 | \c | |
363 | .I archive\c | |
364 | \& specification. (same as `\|\c | |
365 | .B i\c | |
366 | \|'). | |
367 | ||
368 | .TP | |
369 | .B c | |
370 | \c | |
371 | .I Create\c | |
372 | \& the archive. The specified \c | |
373 | .I archive\c | |
374 | \& is always | |
375 | created if it didn't exist, when you request an update. But a warning is | |
376 | issued unless you specify in advance that you expect to create it, by | |
377 | using this modifier. | |
378 | ||
379 | .TP | |
380 | .B f | |
381 | Truncate names in the archive. | |
382 | .B ar | |
383 | will normally permit file names of any length. This will cause it to | |
384 | create archives which are not compatible with the native | |
385 | .B ar | |
386 | program on some systems. If this is a concern, the | |
387 | .B f | |
388 | modifier may be used to truncate file names when putting them in the | |
389 | archive. | |
390 | ||
391 | .TP | |
392 | .B i | |
393 | Insert new files \c | |
394 | .I before\c | |
395 | \& an existing member of the | |
396 | archive. If you use the modifier \c | |
397 | .B i\c | |
398 | \&, the name of an existing archive | |
399 | member must be present as the \c | |
400 | .I membername\c | |
401 | \& argument, before the | |
402 | \c | |
403 | .I archive\c | |
404 | \& specification. (same as `\|\c | |
405 | .B b\c | |
406 | \|'). | |
407 | ||
408 | .TP | |
409 | .B l | |
410 | This modifier is accepted but not used. | |
411 | ||
3de39064 ILT |
412 | .TP |
413 | .B N | |
414 | Uses the | |
415 | .I count | |
416 | parameter. This is used if there are multiple entries in the archive | |
417 | with the same name. Extract or delete instance | |
418 | .I count | |
419 | of the given name from the archive. | |
420 | ||
252b5132 RH |
421 | .TP |
422 | .B o | |
423 | Preserve the \c | |
424 | .I original\c | |
425 | \& dates of members when extracting them. If | |
426 | you do not specify this modifier, files extracted from the archive | |
427 | will be stamped with the time of extraction. | |
428 | ||
3de39064 ILT |
429 | .TP |
430 | .B P | |
431 | Use the full path name when matching names in the archive. | |
432 | .B ar | |
433 | can not create an archive with a full path name (such archives are not | |
434 | POSIX complaint), but other archive creators can. This option will | |
435 | cause | |
436 | .B ar | |
437 | to match file names using a complete path name, which can be | |
438 | convenient when extracting a single file from an archive created by | |
439 | another tool. | |
440 | ||
252b5132 RH |
441 | .TP |
442 | .B s | |
443 | Write an object-file index into the archive, or update an existing one, | |
444 | even if no other change is made to the archive. You may use this modifier | |
445 | flag either with any operation, or alone. Running `\|\c | |
446 | .B ar s\c | |
447 | \|' on an | |
448 | archive is equivalent to running `\|\c | |
449 | .B ranlib\c | |
450 | \|' on it. | |
451 | ||
452 | .TP | |
453 | .B S | |
454 | Do not generate an archive symbol table. This can speed up building a | |
455 | large library in several steps. The resulting archive can not be used | |
456 | with the linker. In order to build a symbol table, you must omit the | |
457 | `\|\c | |
458 | .B S\c | |
459 | \|' modifier on the last execution of `\|\c | |
460 | .B ar\c | |
461 | \|', or you must run `\|\c | |
462 | .B ranlib\c | |
463 | \|' on the archive. | |
464 | ||
465 | .TP | |
466 | .B u | |
467 | Normally, \c | |
468 | .B ar r\c | |
469 | \&.\|.\|. inserts all files | |
470 | listed into the archive. If you would like to insert \c | |
471 | .I only\c | |
472 | \& those | |
473 | of the files you list that are newer than existing members of the same | |
474 | names, use this modifier. The `\|\c | |
475 | .B u\c | |
476 | \|' modifier is allowed only for the | |
477 | operation `\|\c | |
478 | .B r\c | |
479 | \|' (replace). In particular, the combination `\|\c | |
480 | .B qu\c | |
481 | \|' is | |
482 | not allowed, since checking the timestamps would lose any speed | |
483 | advantage from the operation `\|\c | |
484 | .B q\c | |
485 | \|'. | |
486 | ||
487 | .TP | |
488 | .B v | |
489 | This modifier requests the \c | |
490 | .I verbose\c | |
491 | \& version of an operation. Many | |
492 | operations display additional information, such as filenames processed, | |
493 | when the modifier `\|\c | |
494 | .B v\c | |
495 | \|' is appended. | |
496 | ||
497 | .TP | |
498 | .B V | |
499 | This modifier shows the version number of | |
500 | .BR ar . | |
501 | ||
502 | .PP | |
503 | ||
504 | .SH "SEE ALSO" | |
505 | .RB "`\|" binutils "\|'" | |
506 | entry in | |
507 | .B | |
508 | info\c | |
509 | \&; | |
510 | .I | |
511 | The GNU Binary Utilities\c | |
512 | , Roland H. Pesch (October 1991). | |
513 | .BR nm ( 1 )\c | |
514 | \&, | |
515 | .BR ranlib ( 1 )\c | |
516 | \&. | |
517 | ||
518 | .SH COPYING | |
cf055d54 NC |
519 | Copyright (c) 1991, 1992, 1993, 1995, 1998, 1999, 2000 Free Software Foundation, Inc. |
520 | .PP | |
521 | This document is distributed under the terms of the GNU Free | |
e47b9e39 NC |
522 | Documentation License, version 1.1. That license is described in the |
523 | sources for this manual page, but it is not displayed here in order to | |
524 | make this manual more consise. Copies of this license can also be | |
525 | obtained from: http://www.gnu.org/copyleft/. | |
cf055d54 | 526 | |
e47b9e39 NC |
527 | \" .SH GNU Free Documentation License |
528 | \" Version 1.1, March 2000 | |
cf055d54 | 529 | |
e47b9e39 NC |
530 | \" Copyright (C) 2000 Free Software Foundation, Inc. |
531 | \" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
cf055d54 | 532 | |
e47b9e39 NC |
533 | \" Everyone is permitted to copy and distribute verbatim |
534 | \" copies of this license document, but changing it is | |
535 | \" not allowed. | |
536 | \" .PP | |
537 | \" 0. PREAMBLE | |
538 | \" .PP | |
539 | \" The purpose of this License is to make a manual, textbook, or other | |
540 | \" written document "free" in the sense of freedom: to assure everyone | |
541 | \" the effective freedom to copy and redistribute it, with or without | |
542 | \" modifying it, either commercially or noncommercially. Secondarily, | |
543 | \" this License preserves for the author and publisher a way to get | |
544 | \" credit for their work, while not being considered responsible for | |
545 | \" modifications made by others. | |
546 | \" .PP | |
547 | \" This License is a kind of "copyleft", which means that derivative | |
548 | \" works of the document must themselves be free in the same sense. It | |
549 | \" complements the GNU General Public License, which is a copyleft | |
550 | \" license designed for free software. | |
551 | \" .PP | |
552 | \" We have designed this License in order to use it for manuals for free | |
553 | \" software, because free software needs free documentation: a free | |
554 | \" program should come with manuals providing the same freedoms that the | |
555 | \" software does. But this License is not limited to software manuals; | |
556 | \" it can be used for any textual work, regardless of subject matter or | |
557 | \" whether it is published as a printed book. We recommend this License | |
558 | \" principally for works whose purpose is instruction or reference. | |
559 | \" .PP | |
560 | \" 1. APPLICABILITY AND DEFINITIONS | |
561 | \" .PP | |
562 | \" This License applies to any manual or other work that contains a | |
563 | \" notice placed by the copyright holder saying it can be distributed | |
564 | \" under the terms of this License. The "Document", below, refers to any | |
565 | \" such manual or work. Any member of the public is a licensee, and is | |
566 | \" addressed as "you". | |
567 | \" .PP | |
568 | \" A "Modified Version" of the Document means any work containing the | |
569 | \" Document or a portion of it, either copied verbatim, or with | |
570 | \" modifications and/or translated into another language. | |
571 | \" .PP | |
572 | \" A "Secondary Section" is a named appendix or a front-matter section of | |
573 | \" the Document that deals exclusively with the relationship of the | |
574 | \" publishers or authors of the Document to the Document's overall subject | |
575 | \" (or to related matters) and contains nothing that could fall directly | |
576 | \" within that overall subject. (For example, if the Document is in part a | |
577 | \" textbook of mathematics, a Secondary Section may not explain any | |
578 | \" mathematics.) The relationship could be a matter of historical | |
579 | \" connection with the subject or with related matters, or of legal, | |
580 | \" commercial, philosophical, ethical or political position regarding | |
581 | \" them. | |
582 | \" .PP | |
583 | \" The "Invariant Sections" are certain Secondary Sections whose titles | |
584 | \" are designated, as being those of Invariant Sections, in the notice | |
585 | \" that says that the Document is released under this License. | |
586 | \" .PP | |
587 | \" The "Cover Texts" are certain short passages of text that are listed, | |
588 | \" as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
589 | \" the Document is released under this License. | |
590 | \" .PP | |
591 | \" A "Transparent" copy of the Document means a machine-readable copy, | |
592 | \" represented in a format whose specification is available to the | |
593 | \" general public, whose contents can be viewed and edited directly and | |
594 | \" straightforwardly with generic text editors or (for images composed of | |
595 | \" pixels) generic paint programs or (for drawings) some widely available | |
596 | \" drawing editor, and that is suitable for input to text formatters or | |
597 | \" for automatic translation to a variety of formats suitable for input | |
598 | \" to text formatters. A copy made in an otherwise Transparent file | |
599 | \" format whose markup has been designed to thwart or discourage | |
600 | \" subsequent modification by readers is not Transparent. A copy that is | |
601 | \" not "Transparent" is called "Opaque". | |
602 | \" .PP | |
603 | \" Examples of suitable formats for Transparent copies include plain | |
604 | \" ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
605 | \" or XML using a publicly available DTD, and standard-conforming simple | |
606 | \" HTML designed for human modification. Opaque formats include | |
607 | \" PostScript, PDF, proprietary formats that can be read and edited only | |
608 | \" by proprietary word processors, SGML or XML for which the DTD and/or | |
609 | \" processing tools are not generally available, and the | |
610 | \" machine-generated HTML produced by some word processors for output | |
611 | \" purposes only. | |
612 | \" .PP | |
613 | \" The "Title Page" means, for a printed book, the title page itself, | |
614 | \" plus such following pages as are needed to hold, legibly, the material | |
615 | \" this License requires to appear in the title page. For works in | |
616 | \" formats which do not have any title page as such, "Title Page" means | |
617 | \" the text near the most prominent appearance of the work's title, | |
618 | \" preceding the beginning of the body of the text. | |
619 | \" .PP | |
620 | \" 2. VERBATIM COPYING | |
621 | \" .PP | |
622 | \" You may copy and distribute the Document in any medium, either | |
623 | \" commercially or noncommercially, provided that this License, the | |
624 | \" copyright notices, and the license notice saying this License applies | |
625 | \" to the Document are reproduced in all copies, and that you add no other | |
626 | \" conditions whatsoever to those of this License. You may not use | |
627 | \" technical measures to obstruct or control the reading or further | |
628 | \" copying of the copies you make or distribute. However, you may accept | |
629 | \" compensation in exchange for copies. If you distribute a large enough | |
630 | \" number of copies you must also follow the conditions in section 3. | |
631 | \" .PP | |
632 | \" You may also lend copies, under the same conditions stated above, and | |
633 | \" you may publicly display copies. | |
634 | \" .PP | |
635 | \" 3. COPYING IN QUANTITY | |
636 | \" .PP | |
637 | \" If you publish printed copies of the Document numbering more than 100, | |
638 | \" and the Document's license notice requires Cover Texts, you must enclose | |
639 | \" the copies in covers that carry, clearly and legibly, all these Cover | |
640 | \" Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
641 | \" the back cover. Both covers must also clearly and legibly identify | |
642 | \" you as the publisher of these copies. The front cover must present | |
643 | \" the full title with all words of the title equally prominent and | |
644 | \" visible. You may add other material on the covers in addition. | |
645 | \" Copying with changes limited to the covers, as long as they preserve | |
646 | \" the title of the Document and satisfy these conditions, can be treated | |
647 | \" as verbatim copying in other respects. | |
648 | \" .PP | |
649 | \" If the required texts for either cover are too voluminous to fit | |
650 | \" legibly, you should put the first ones listed (as many as fit | |
651 | \" reasonably) on the actual cover, and continue the rest onto adjacent | |
652 | \" pages. | |
653 | \" .PP | |
654 | \" If you publish or distribute Opaque copies of the Document numbering | |
655 | \" more than 100, you must either include a machine-readable Transparent | |
656 | \" copy along with each Opaque copy, or state in or with each Opaque copy | |
657 | \" a publicly-accessible computer-network location containing a complete | |
658 | \" Transparent copy of the Document, free of added material, which the | |
659 | \" general network-using public has access to download anonymously at no | |
660 | \" charge using public-standard network protocols. If you use the latter | |
661 | \" option, you must take reasonably prudent steps, when you begin | |
662 | \" distribution of Opaque copies in quantity, to ensure that this | |
663 | \" Transparent copy will remain thus accessible at the stated location | |
664 | \" until at least one year after the last time you distribute an Opaque | |
665 | \" copy (directly or through your agents or retailers) of that edition to | |
666 | \" the public. | |
667 | \" .PP | |
668 | \" It is requested, but not required, that you contact the authors of the | |
669 | \" Document well before redistributing any large number of copies, to give | |
670 | \" them a chance to provide you with an updated version of the Document. | |
671 | \" .PP | |
672 | \" 4. MODIFICATIONS | |
673 | \" .PP | |
674 | \" You may copy and distribute a Modified Version of the Document under | |
675 | \" the conditions of sections 2 and 3 above, provided that you release | |
676 | \" the Modified Version under precisely this License, with the Modified | |
677 | \" Version filling the role of the Document, thus licensing distribution | |
678 | \" and modification of the Modified Version to whoever possesses a copy | |
679 | \" of it. In addition, you must do these things in the Modified Version: | |
680 | \" .PP | |
681 | \" A. Use in the Title Page (and on the covers, if any) a title distinct | |
682 | \" from that of the Document, and from those of previous versions | |
683 | \" (which should, if there were any, be listed in the History section | |
684 | \" of the Document). You may use the same title as a previous version | |
685 | \" if the original publisher of that version gives permission. | |
686 | \" .PP | |
687 | \" B. List on the Title Page, as authors, one or more persons or entities | |
688 | \" responsible for authorship of the modifications in the Modified | |
689 | \" Version, together with at least five of the principal authors of the | |
690 | \" Document (all of its principal authors, if it has less than five). | |
691 | \" .PP | |
692 | \" C. State on the Title page the name of the publisher of the | |
693 | \" Modified Version, as the publisher. | |
694 | \" .PP | |
695 | \" D. Preserve all the copyright notices of the Document. | |
696 | \" .PP | |
697 | \" E. Add an appropriate copyright notice for your modifications | |
698 | \" adjacent to the other copyright notices. | |
699 | \" .PP | |
700 | \" F. Include, immediately after the copyright notices, a license notice | |
701 | \" giving the public permission to use the Modified Version under the | |
702 | \" terms of this License, in the form shown in the Addendum below. | |
703 | \" Preserve in that license notice the full lists of Invariant Sections | |
704 | \" and required Cover Texts given in the Document's license notice. | |
705 | \" .PP | |
706 | \" H. Include an unaltered copy of this License. | |
707 | \" .PP | |
708 | \" I. Preserve the section entitled "History", and its title, and add to | |
709 | \" it an item stating at least the title, year, new authors, and | |
710 | \" publisher of the Modified Version as given on the Title Page. If | |
711 | \" there is no section entitled "History" in the Document, create one | |
712 | \" stating the title, year, authors, and publisher of the Document as | |
713 | \" given on its Title Page, then add an item describing the Modified | |
714 | \" Version as stated in the previous sentence. | |
715 | \" .PP | |
716 | \" J. Preserve the network location, if any, given in the Document for | |
717 | \" public access to a Transparent copy of the Document, and likewise | |
718 | \" the network locations given in the Document for previous versions | |
719 | \" it was based on. These may be placed in the "History" section. | |
720 | \" You may omit a network location for a work that was published at | |
721 | \" least four years before the Document itself, or if the original | |
722 | \" publisher of the version it refers to gives permission. | |
723 | \" .PP | |
724 | \" K. In any section entitled "Acknowledgements" or "Dedications", | |
725 | \" preserve the section's title, and preserve in the section all the | |
726 | \" substance and tone of each of the contributor acknowledgements | |
727 | \" and/or dedications given therein. | |
728 | \" .PP | |
729 | \" L. Preserve all the Invariant Sections of the Document, | |
730 | \" unaltered in their text and in their titles. Section numbers | |
731 | \" or the equivalent are not considered part of the section titles. | |
732 | \" .PP | |
733 | \" M. Delete any section entitled "Endorsements". Such a section | |
734 | \" may not be included in the Modified Version. | |
735 | \" .PP | |
736 | \" N. Do not retitle any existing section as "Endorsements" | |
737 | \" or to conflict in title with any Invariant Section. | |
738 | \" .PP | |
739 | \" If the Modified Version includes new front-matter sections or | |
740 | \" appendices that qualify as Secondary Sections and contain no material | |
741 | \" copied from the Document, you may at your option designate some or all | |
742 | \" of these sections as invariant. To do this, add their titles to the | |
743 | \" list of Invariant Sections in the Modified Version's license notice. | |
744 | \" These titles must be distinct from any other section titles. | |
745 | \" .PP | |
746 | \" You may add a section entitled "Endorsements", provided it contains | |
747 | \" nothing but endorsements of your Modified Version by various | |
748 | \" parties--for example, statements of peer review or that the text has | |
749 | \" been approved by an organization as the authoritative definition of a | |
750 | \" standard. | |
751 | \" .PP | |
752 | \" You may add a passage of up to five words as a Front-Cover Text, and a | |
753 | \" passage of up to 25 words as a Back-Cover Text, to the end of the list | |
754 | \" of Cover Texts in the Modified Version. Only one passage of | |
755 | \" Front-Cover Text and one of Back-Cover Text may be added by (or | |
756 | \" through arrangements made by) any one entity. If the Document already | |
757 | \" includes a cover text for the same cover, previously added by you or | |
758 | \" by arrangement made by the same entity you are acting on behalf of, | |
759 | \" you may not add another; but you may replace the old one, on explicit | |
760 | \" permission from the previous publisher that added the old one. | |
761 | \" .PP | |
762 | \" The author(s) and publisher(s) of the Document do not by this License | |
763 | \" give permission to use their names for publicity for or to assert or | |
764 | \" imply endorsement of any Modified Version. | |
765 | \" .PP | |
766 | ||
767 | \" 5. COMBINING DOCUMENTS | |
768 | \" .PP | |
769 | \" You may combine the Document with other documents released under this | |
770 | \" License, under the terms defined in section 4 above for modified | |
771 | \" versions, provided that you include in the combination all of the | |
772 | \" Invariant Sections of all of the original documents, unmodified, and | |
773 | \" list them all as Invariant Sections of your combined work in its | |
774 | \" license notice. | |
775 | \" .PP | |
776 | \" The combined work need only contain one copy of this License, and | |
777 | \" multiple identical Invariant Sections may be replaced with a single | |
778 | \" copy. If there are multiple Invariant Sections with the same name but | |
779 | \" different contents, make the title of each such section unique by | |
780 | \" adding at the end of it, in parentheses, the name of the original | |
781 | \" author or publisher of that section if known, or else a unique number. | |
782 | \" Make the same adjustment to the section titles in the list of | |
783 | \" Invariant Sections in the license notice of the combined work. | |
784 | \" .PP | |
785 | \" In the combination, you must combine any sections entitled "History" | |
786 | \" in the various original documents, forming one section entitled | |
787 | \" "History"; likewise combine any sections entitled "Acknowledgements", | |
788 | \" and any sections entitled "Dedications". You must delete all sections | |
789 | \" entitled "Endorsements." | |
790 | \" .PP | |
791 | ||
792 | \" 6. COLLECTIONS OF DOCUMENTS | |
793 | \" .PP | |
794 | \" You may make a collection consisting of the Document and other documents | |
795 | \" released under this License, and replace the individual copies of this | |
796 | \" License in the various documents with a single copy that is included in | |
797 | \" the collection, provided that you follow the rules of this License for | |
798 | \" verbatim copying of each of the documents in all other respects. | |
799 | \" .PP | |
800 | \" You may extract a single document from such a collection, and distribute | |
801 | \" it individually under this License, provided you insert a copy of this | |
802 | \" License into the extracted document, and follow this License in all | |
803 | \" other respects regarding verbatim copying of that document. | |
804 | \" .PP | |
805 | ||
806 | \" 7. AGGREGATION WITH INDEPENDENT WORKS | |
807 | \" .PP | |
808 | \" A compilation of the Document or its derivatives with other separate | |
809 | \" and independent documents or works, in or on a volume of a storage or | |
810 | \" distribution medium, does not as a whole count as a Modified Version | |
811 | \" of the Document, provided no compilation copyright is claimed for the | |
812 | \" compilation. Such a compilation is called an "aggregate", and this | |
813 | \" License does not apply to the other self-contained works thus compiled | |
814 | \" with the Document, on account of their being thus compiled, if they | |
815 | \" are not themselves derivative works of the Document. | |
816 | \" .PP | |
817 | \" If the Cover Text requirement of section 3 is applicable to these | |
818 | \" copies of the Document, then if the Document is less than one quarter | |
819 | \" of the entire aggregate, the Document's Cover Texts may be placed on | |
820 | \" covers that surround only the Document within the aggregate. | |
821 | \" Otherwise they must appear on covers around the whole aggregate. | |
822 | \" .PP | |
823 | ||
824 | \" 8. TRANSLATION | |
825 | \" .PP | |
826 | \" Translation is considered a kind of modification, so you may | |
827 | \" distribute translations of the Document under the terms of section 4. | |
828 | \" Replacing Invariant Sections with translations requires special | |
829 | \" permission from their copyright holders, but you may include | |
830 | \" translations of some or all Invariant Sections in addition to the | |
831 | \" original versions of these Invariant Sections. You may include a | |
832 | \" translation of this License provided that you also include the | |
833 | \" original English version of this License. In case of a disagreement | |
834 | \" between the translation and the original English version of this | |
835 | \" License, the original English version will prevail. | |
836 | \" .PP | |
837 | ||
838 | \" 9. TERMINATION | |
839 | \" .PP | |
840 | \" You may not copy, modify, sublicense, or distribute the Document except | |
841 | \" as expressly provided for under this License. Any other attempt to | |
842 | \" copy, modify, sublicense or distribute the Document is void, and will | |
843 | \" automatically terminate your rights under this License. However, | |
844 | \" parties who have received copies, or rights, from you under this | |
845 | \" License will not have their licenses terminated so long as such | |
846 | \" parties remain in full compliance. | |
847 | \" .PP | |
848 | ||
849 | \" 10. FUTURE REVISIONS OF THIS LICENSE | |
850 | \" .PP | |
851 | \" The Free Software Foundation may publish new, revised versions | |
852 | \" of the GNU Free Documentation License from time to time. Such new | |
853 | \" versions will be similar in spirit to the present version, but may | |
854 | \" differ in detail to address new problems or concerns. See | |
855 | \" http://www.gnu.org/copyleft/. | |
856 | \" .PP | |
857 | \" Each version of the License is given a distinguishing version number. | |
858 | \" If the Document specifies that a particular numbered version of this | |
859 | \" License "or any later version" applies to it, you have the option of | |
860 | \" following the terms and conditions either of that specified version or | |
861 | \" of any later version that has been published (not as a draft) by the | |
862 | \" Free Software Foundation. If the Document does not specify a version | |
863 | \" number of this License, you may choose any version ever published (not | |
864 | \" as a draft) by the Free Software Foundation. | |
865 | \" .PP | |
866 | ||
867 | \" ADDENDUM: How to use this License for your documents | |
868 | \" .PP | |
869 | \" To use this License in a document you have written, include a copy of | |
870 | \" the License in the document and put the following copyright and | |
871 | \" license notices just after the title page: | |
872 | \" .PP | |
873 | \" Copyright (c) YEAR YOUR NAME. | |
874 | \" Permission is granted to copy, distribute and/or | |
875 | \" modify this document under the terms of the GNU | |
876 | \" Free Documentation License, Version 1.1 or any later | |
877 | \" version published by the Free Software Foundation; | |
878 | \" with the Invariant Sections being LIST THEIR TITLES, | |
879 | \" with the Front-Cover Texts being LIST, and with the | |
880 | \" Back-Cover Texts being LIST. A copy of the license | |
881 | \" is included in the section entitled "GNU Free | |
882 | \" Documentation License". | |
883 | \" .PP | |
884 | \" If you have no Invariant Sections, write "with no Invariant Sections" | |
885 | \" instead of saying which ones are invariant. If you have no | |
886 | \" Front-Cover Texts, write "no Front-Cover Texts" instead of | |
887 | \" "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. | |
888 | \" .PP | |
889 | \" If your document contains nontrivial examples of program code, we | |
890 | \" recommend releasing these examples in parallel under your choice of | |
891 | \" free software license, such as the GNU General Public License, | |
892 | \" to permit their use in free software. |