binutils/ar.1

   1 .\" Copyright (c) 1991, 1992, 1993, 1995, 1998, 1999, 2000 Free Software Foundation
   2 .\" See section COPYING for conditions for redistribution
   3 .TH ar 1 "1999" "Free Software Foundation" "GNU Development Tools"
   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
  17 .I {dmpqrtx}[abcfilNoPsSuvV] \c
  18 [\|\c
  19 .I membername\c
  20 \&\|] \c
  21 [\|\c
  22 .I count\c
  23 \&\|] \c
  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
 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
 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
 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
 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
 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
 521 Documenation License.  That license is described in the GNU Free
 522 Documentation License section.
 523
 524 .SH GNU Free Documentation License
 525   Version 1.1, March 2000
 526
 527   Copyright (C) 2000  Free Software Foundation, Inc.
 528   59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 529
 530   Everyone is permitted to copy and distribute verbatim
 531   copies of this license document, but changing it is
 532   not allowed.
 533 .PP
 534 0. PREAMBLE
 535 .PP
 536 The purpose of this License is to make a manual, textbook, or other
 537 written document "free" in the sense of freedom: to assure everyone
 538 the effective freedom to copy and redistribute it, with or without
 539 modifying it, either commercially or noncommercially.  Secondarily,
 540 this License preserves for the author and publisher a way to get
 541 credit for their work, while not being considered responsible for
 542 modifications made by others.
 543 .PP
 544 This License is a kind of "copyleft", which means that derivative
 545 works of the document must themselves be free in the same sense.  It
 546 complements the GNU General Public License, which is a copyleft
 547 license designed for free software.
 548 .PP
 549 We have designed this License in order to use it for manuals for free
 550 software, because free software needs free documentation: a free
 551 program should come with manuals providing the same freedoms that the
 552 software does.  But this License is not limited to software manuals;
 553 it can be used for any textual work, regardless of subject matter or
 554 whether it is published as a printed book.  We recommend this License
 555 principally for works whose purpose is instruction or reference.
 556 .PP
 557 1. APPLICABILITY AND DEFINITIONS
 558 .PP
 559 This License applies to any manual or other work that contains a
 560 notice placed by the copyright holder saying it can be distributed
 561 under the terms of this License.  The "Document", below, refers to any
 562 such manual or work.  Any member of the public is a licensee, and is
 563 addressed as "you".
 564 .PP
 565 A "Modified Version" of the Document means any work containing the
 566 Document or a portion of it, either copied verbatim, or with
 567 modifications and/or translated into another language.
 568 .PP
 569 A "Secondary Section" is a named appendix or a front-matter section of
 570 the Document that deals exclusively with the relationship of the
 571 publishers or authors of the Document to the Document's overall subject
 572 (or to related matters) and contains nothing that could fall directly
 573 within that overall subject.  (For example, if the Document is in part a
 574 textbook of mathematics, a Secondary Section may not explain any
 575 mathematics.)  The relationship could be a matter of historical
 576 connection with the subject or with related matters, or of legal,
 577 commercial, philosophical, ethical or political position regarding
 578 them.
 579 .PP
 580 The "Invariant Sections" are certain Secondary Sections whose titles
 581 are designated, as being those of Invariant Sections, in the notice
 582 that says that the Document is released under this License.
 583 .PP
 584 The "Cover Texts" are certain short passages of text that are listed,
 585 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
 586 the Document is released under this License.
 587 .PP
 588 A "Transparent" copy of the Document means a machine-readable copy,
 589 represented in a format whose specification is available to the
 590 general public, whose contents can be viewed and edited directly and
 591 straightforwardly with generic text editors or (for images composed of
 592 pixels) generic paint programs or (for drawings) some widely available
 593 drawing editor, and that is suitable for input to text formatters or
 594 for automatic translation to a variety of formats suitable for input
 595 to text formatters.  A copy made in an otherwise Transparent file
 596 format whose markup has been designed to thwart or discourage
 597 subsequent modification by readers is not Transparent.  A copy that is
 598 not "Transparent" is called "Opaque".
 599 .PP
 600 Examples of suitable formats for Transparent copies include plain
 601 ASCII without markup, Texinfo input format, LaTeX input format, SGML
 602 or XML using a publicly available DTD, and standard-conforming simple
 603 HTML designed for human modification.  Opaque formats include
 604 PostScript, PDF, proprietary formats that can be read and edited only
 605 by proprietary word processors, SGML or XML for which the DTD and/or
 606 processing tools are not generally available, and the
 607 machine-generated HTML produced by some word processors for output
 608 purposes only.
 609 .PP
 610 The "Title Page" means, for a printed book, the title page itself,
 611 plus such following pages as are needed to hold, legibly, the material
 612 this License requires to appear in the title page.  For works in
 613 formats which do not have any title page as such, "Title Page" means
 614 the text near the most prominent appearance of the work's title,
 615 preceding the beginning of the body of the text.
 616 .PP
 617 2. VERBATIM COPYING
 618 .PP
 619 You may copy and distribute the Document in any medium, either
 620 commercially or noncommercially, provided that this License, the
 621 copyright notices, and the license notice saying this License applies
 622 to the Document are reproduced in all copies, and that you add no other
 623 conditions whatsoever to those of this License.  You may not use
 624 technical measures to obstruct or control the reading or further
 625 copying of the copies you make or distribute.  However, you may accept
 626 compensation in exchange for copies.  If you distribute a large enough
 627 number of copies you must also follow the conditions in section 3.
 628 .PP
 629 You may also lend copies, under the same conditions stated above, and
 630 you may publicly display copies.
 631 .PP
 632 3. COPYING IN QUANTITY
 633 .PP
 634 If you publish printed copies of the Document numbering more than 100,
 635 and the Document's license notice requires Cover Texts, you must enclose
 636 the copies in covers that carry, clearly and legibly, all these Cover
 637 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
 638 the back cover.  Both covers must also clearly and legibly identify
 639 you as the publisher of these copies.  The front cover must present
 640 the full title with all words of the title equally prominent and
 641 visible.  You may add other material on the covers in addition.
 642 Copying with changes limited to the covers, as long as they preserve
 643 the title of the Document and satisfy these conditions, can be treated
 644 as verbatim copying in other respects.
 645 .PP
 646 If the required texts for either cover are too voluminous to fit
 647 legibly, you should put the first ones listed (as many as fit
 648 reasonably) on the actual cover, and continue the rest onto adjacent
 649 pages.
 650 .PP
 651 If you publish or distribute Opaque copies of the Document numbering
 652 more than 100, you must either include a machine-readable Transparent
 653 copy along with each Opaque copy, or state in or with each Opaque copy
 654 a publicly-accessible computer-network location containing a complete
 655 Transparent copy of the Document, free of added material, which the
 656 general network-using public has access to download anonymously at no
 657 charge using public-standard network protocols.  If you use the latter
 658 option, you must take reasonably prudent steps, when you begin
 659 distribution of Opaque copies in quantity, to ensure that this
 660 Transparent copy will remain thus accessible at the stated location
 661 until at least one year after the last time you distribute an Opaque
 662 copy (directly or through your agents or retailers) of that edition to
 663 the public.
 664 .PP
 665 It is requested, but not required, that you contact the authors of the
 666 Document well before redistributing any large number of copies, to give
 667 them a chance to provide you with an updated version of the Document.
 668 .PP
 669 4. MODIFICATIONS
 670 .PP
 671 You may copy and distribute a Modified Version of the Document under
 672 the conditions of sections 2 and 3 above, provided that you release
 673 the Modified Version under precisely this License, with the Modified
 674 Version filling the role of the Document, thus licensing distribution
 675 and modification of the Modified Version to whoever possesses a copy
 676 of it.  In addition, you must do these things in the Modified Version:
 677 .PP
 678 A. Use in the Title Page (and on the covers, if any) a title distinct
 679 from that of the Document, and from those of previous versions
 680 (which should, if there were any, be listed in the History section
 681 of the Document).  You may use the same title as a previous version
 682 if the original publisher of that version gives permission.
 683 .PP
 684 B. List on the Title Page, as authors, one or more persons or entities
 685 responsible for authorship of the modifications in the Modified
 686 Version, together with at least five of the principal authors of the
 687 Document (all of its principal authors, if it has less than five).
 688 .PP
 689 C. State on the Title page the name of the publisher of the
 690 Modified Version, as the publisher.
 691 .PP
 692 D. Preserve all the copyright notices of the Document.
 693 .PP
 694 E. Add an appropriate copyright notice for your modifications
 695 adjacent to the other copyright notices.
 696 .PP
 697 F. Include, immediately after the copyright notices, a license notice
 698 giving the public permission to use the Modified Version under the
 699 terms of this License, in the form shown in the Addendum below.
 700 Preserve in that license notice the full lists of Invariant Sections
 701 and required Cover Texts given in the Document's license notice.
 702 .PP
 703 H. Include an unaltered copy of this License.
 704 .PP
 705 I. Preserve the section entitled "History", and its title, and add to
 706 it an item stating at least the title, year, new authors, and
 707 publisher of the Modified Version as given on the Title Page.  If
 708 there is no section entitled "History" in the Document, create one
 709 stating the title, year, authors, and publisher of the Document as
 710 given on its Title Page, then add an item describing the Modified
 711 Version as stated in the previous sentence.
 712 .PP
 713 J. Preserve the network location, if any, given in the Document for
 714 public access to a Transparent copy of the Document, and likewise
 715 the network locations given in the Document for previous versions
 716 it was based on.  These may be placed in the "History" section.
 717 You may omit a network location for a work that was published at
 718 least four years before the Document itself, or if the original
 719 publisher of the version it refers to gives permission.
 720 .PP
 721 K. In any section entitled "Acknowledgements" or "Dedications",
 722 preserve the section's title, and preserve in the section all the
 723 substance and tone of each of the contributor acknowledgements
 724 and/or dedications given therein.
 725 .PP
 726 L. Preserve all the Invariant Sections of the Document,
 727 unaltered in their text and in their titles.  Section numbers
 728 or the equivalent are not considered part of the section titles.
 729 .PP
 730 M. Delete any section entitled "Endorsements".  Such a section
 731 may not be included in the Modified Version.
 732 .PP
 733 N. Do not retitle any existing section as "Endorsements"
 734 or to conflict in title with any Invariant Section.
 735 .PP
 736 If the Modified Version includes new front-matter sections or
 737 appendices that qualify as Secondary Sections and contain no material
 738 copied from the Document, you may at your option designate some or all
 739 of these sections as invariant.  To do this, add their titles to the
 740 list of Invariant Sections in the Modified Version's license notice.
 741 These titles must be distinct from any other section titles.
 742 .PP
 743 You may add a section entitled "Endorsements", provided it contains
 744 nothing but endorsements of your Modified Version by various
 745 parties--for example, statements of peer review or that the text has
 746 been approved by an organization as the authoritative definition of a
 747 standard.
 748 .PP
 749 You may add a passage of up to five words as a Front-Cover Text, and a
 750 passage of up to 25 words as a Back-Cover Text, to the end of the list
 751 of Cover Texts in the Modified Version.  Only one passage of
 752 Front-Cover Text and one of Back-Cover Text may be added by (or
 753 through arrangements made by) any one entity.  If the Document already
 754 includes a cover text for the same cover, previously added by you or
 755 by arrangement made by the same entity you are acting on behalf of,
 756 you may not add another; but you may replace the old one, on explicit
 757 permission from the previous publisher that added the old one.
 758 .PP
 759 The author(s) and publisher(s) of the Document do not by this License
 760 give permission to use their names for publicity for or to assert or
 761 imply endorsement of any Modified Version.
 762 .PP
 763
 764 5. COMBINING DOCUMENTS
 765 .PP
 766 You may combine the Document with other documents released under this
 767 License, under the terms defined in section 4 above for modified
 768 versions, provided that you include in the combination all of the
 769 Invariant Sections of all of the original documents, unmodified, and
 770 list them all as Invariant Sections of your combined work in its
 771 license notice.
 772 .PP
 773 The combined work need only contain one copy of this License, and
 774 multiple identical Invariant Sections may be replaced with a single
 775 copy.  If there are multiple Invariant Sections with the same name but
 776 different contents, make the title of each such section unique by
 777 adding at the end of it, in parentheses, the name of the original
 778 author or publisher of that section if known, or else a unique number.
 779 Make the same adjustment to the section titles in the list of
 780 Invariant Sections in the license notice of the combined work.
 781 .PP
 782 In the combination, you must combine any sections entitled "History"
 783 in the various original documents, forming one section entitled
 784 "History"; likewise combine any sections entitled "Acknowledgements",
 785 and any sections entitled "Dedications".  You must delete all sections
 786 entitled "Endorsements."
 787 .PP
 788
 789 6. COLLECTIONS OF DOCUMENTS
 790 .PP
 791 You may make a collection consisting of the Document and other documents
 792 released under this License, and replace the individual copies of this
 793 License in the various documents with a single copy that is included in
 794 the collection, provided that you follow the rules of this License for
 795 verbatim copying of each of the documents in all other respects.
 796 .PP
 797 You may extract a single document from such a collection, and distribute
 798 it individually under this License, provided you insert a copy of this
 799 License into the extracted document, and follow this License in all
 800 other respects regarding verbatim copying of that document.
 801 .PP
 802
 803 7. AGGREGATION WITH INDEPENDENT WORKS
 804 .PP
 805 A compilation of the Document or its derivatives with other separate
 806 and independent documents or works, in or on a volume of a storage or
 807 distribution medium, does not as a whole count as a Modified Version
 808 of the Document, provided no compilation copyright is claimed for the
 809 compilation.  Such a compilation is called an "aggregate", and this
 810 License does not apply to the other self-contained works thus compiled
 811 with the Document, on account of their being thus compiled, if they
 812 are not themselves derivative works of the Document.
 813 .PP
 814 If the Cover Text requirement of section 3 is applicable to these
 815 copies of the Document, then if the Document is less than one quarter
 816 of the entire aggregate, the Document's Cover Texts may be placed on
 817 covers that surround only the Document within the aggregate.
 818 Otherwise they must appear on covers around the whole aggregate.
 819 .PP
 820
 821 8. TRANSLATION
 822 .PP
 823 Translation is considered a kind of modification, so you may
 824 distribute translations of the Document under the terms of section 4.
 825 Replacing Invariant Sections with translations requires special
 826 permission from their copyright holders, but you may include
 827 translations of some or all Invariant Sections in addition to the
 828 original versions of these Invariant Sections.  You may include a
 829 translation of this License provided that you also include the
 830 original English version of this License.  In case of a disagreement
 831 between the translation and the original English version of this
 832 License, the original English version will prevail.
 833 .PP
 834
 835 9. TERMINATION
 836 .PP
 837 You may not copy, modify, sublicense, or distribute the Document except
 838 as expressly provided for under this License.  Any other attempt to
 839 copy, modify, sublicense or distribute the Document is void, and will
 840 automatically terminate your rights under this License.  However,
 841 parties who have received copies, or rights, from you under this
 842 License will not have their licenses terminated so long as such
 843 parties remain in full compliance.
 844 .PP
 845
 846 10. FUTURE REVISIONS OF THIS LICENSE
 847 .PP
 848 The Free Software Foundation may publish new, revised versions
 849 of the GNU Free Documentation License from time to time.  Such new
 850 versions will be similar in spirit to the present version, but may
 851 differ in detail to address new problems or concerns.  See
 852 http://www.gnu.org/copyleft/.
 853 .PP
 854 Each version of the License is given a distinguishing version number.
 855 If the Document specifies that a particular numbered version of this
 856 License "or any later version" applies to it, you have the option of
 857 following the terms and conditions either of that specified version or
 858 of any later version that has been published (not as a draft) by the
 859 Free Software Foundation.  If the Document does not specify a version
 860 number of this License, you may choose any version ever published (not
 861 as a draft) by the Free Software Foundation.
 862 .PP
 863
 864 ADDENDUM: How to use this License for your documents
 865 .PP
 866 To use this License in a document you have written, include a copy of
 867 the License in the document and put the following copyright and
 868 license notices just after the title page:
 869 .PP
 870     Copyright (c)  YEAR  YOUR NAME.
 871     Permission is granted to copy, distribute and/or
 872     modify this document under the terms of the GNU
 873     Free Documentation License, Version 1.1 or any later
 874     version published by the Free Software Foundation;
 875     with the Invariant Sections being LIST THEIR TITLES,
 876     with the Front-Cover Texts being LIST, and with the
 877     Back-Cover Texts being LIST.  A copy of the license
 878     is included in the section entitled "GNU Free
 879     Documentation License".
 880 .PP
 881 If you have no Invariant Sections, write "with no Invariant Sections"
 882 instead of saying which ones are invariant.  If you have no
 883 Front-Cover Texts, write "no Front-Cover Texts" instead of
 884 "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
 885 .PP
 886 If your document contains nontrivial examples of program code, we
 887 recommend releasing these examples in parallel under your choice of
 888 free software license, such as the GNU General Public License,
 889 to permit their use in free software.