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