| 1 | .\" Copyright (c) 1991 Free Software Foundation |
| 2 | .\" See section COPYING for conditions for redistribution |
| 3 | .TH ar 1 "5 November 1991" "cygnus support" "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}[abcilosuvV] \c |
| 18 | [\|\c |
| 19 | .I membername\c |
| 20 | \&\|] \c |
| 21 | .I archive\c |
| 22 | \& \c |
| 23 | .I files\c |
| 24 | \&.\|.\|. |
| 25 | |
| 26 | .ad b |
| 27 | .hy 1 |
| 28 | .SH DESCRIPTION |
| 29 | The GNU \c |
| 30 | .B ar\c |
| 31 | \& program creates, modifies, and extracts from |
| 32 | archives. An \c |
| 33 | .I archive\c |
| 34 | \& is a single file holding a collection of |
| 35 | other files in a structure that makes it possible to retrieve |
| 36 | the original individual files (called \c |
| 37 | .I members\c |
| 38 | \& of the archive). |
| 39 | |
| 40 | The original files' contents, mode (permissions), timestamp, owner, and |
| 41 | group are preserved in the archive, and may be reconstituted on |
| 42 | extraction. |
| 43 | |
| 44 | GNU \c |
| 45 | .B ar\c |
| 46 | \& can maintain archives whose members have names of any |
| 47 | length; however, depending on how \c |
| 48 | .B ar\c |
| 49 | \& is configured on your |
| 50 | system, a limit on member-name length may be imposed (for compatibility |
| 51 | with archive formats maintained with other tools). If it exists, the |
| 52 | limit is often 15 characters (typical of formats related to a.out) or 16 |
| 53 | characters (typical of formats related to coff). |
| 54 | |
| 55 | \c |
| 56 | .B ar\c |
| 57 | \& is considered a binary utility because archives of this sort |
| 58 | are most often used as \c |
| 59 | .I libraries\c |
| 60 | \& holding commonly needed |
| 61 | subroutines. |
| 62 | |
| 63 | \c |
| 64 | .B ar\c |
| 65 | \& will create an index to the symbols defined in relocatable |
| 66 | object modules in the archive when you specify the modifier `\|\c |
| 67 | .B s\c |
| 68 | \|'. |
| 69 | Once created, this index is updated in the archive whenever \c |
| 70 | .B ar\c |
| 71 | \& |
| 72 | makes a change to its contents (save for the `\|\c |
| 73 | .B q\c |
| 74 | \|' update operation). |
| 75 | An archive with such an index speeds up linking to the library, and |
| 76 | allows routines in the library to call each other without regard to |
| 77 | their placement in the archive. |
| 78 | |
| 79 | You may use `\|\c |
| 80 | .B nm \-s\c |
| 81 | \|' or `\|\c |
| 82 | .B nm \-\-print\-armap\c |
| 83 | \|' to list this index |
| 84 | table. If an archive lacks the table, another form of \c |
| 85 | .B ar\c |
| 86 | \& called |
| 87 | \c |
| 88 | .B ranlib\c |
| 89 | \& can be used to add just the table. |
| 90 | |
| 91 | \c |
| 92 | .B ar\c |
| 93 | \& insists on at least two arguments to execute: one |
| 94 | keyletter specifying the \c |
| 95 | .I operation\c |
| 96 | \& (optionally accompanied by other |
| 97 | keyletters specifying \c |
| 98 | .I modifiers\c |
| 99 | \&), and the archive name to act on. |
| 100 | |
| 101 | Most operations can also accept further \c |
| 102 | .I files\c |
| 103 | \& arguments, |
| 104 | specifying particular files to operate on. |
| 105 | |
| 106 | .SH OPTIONS |
| 107 | GNU \c |
| 108 | .B ar\c |
| 109 | \& allows you to mix the operation code \c |
| 110 | .I p\c |
| 111 | \& and modifier |
| 112 | flags \c |
| 113 | .I mod\c |
| 114 | \& in any order, within the first command-line argument. |
| 115 | |
| 116 | If you wish, you may begin the first command-line argument with a |
| 117 | dash. |
| 118 | |
| 119 | The \c |
| 120 | .I p\c |
| 121 | \& keyletter specifies what operation to execute; it may be |
| 122 | any of the following, but you must specify only one of them: |
| 123 | |
| 124 | .TP |
| 125 | .B d |
| 126 | \c |
| 127 | .I Delete\c |
| 128 | \& modules from the archive. Specify the names of modules to |
| 129 | be deleted as \c |
| 130 | .I files\c |
| 131 | \&; the archive is untouched if you |
| 132 | specify no files to delete. |
| 133 | |
| 134 | If you specify the `\|\c |
| 135 | .B v\c |
| 136 | \|' modifier, \c |
| 137 | .B ar\c |
| 138 | \& will list each module |
| 139 | as it is deleted. |
| 140 | |
| 141 | .TP |
| 142 | .B m |
| 143 | Use this operation to \c |
| 144 | .I move\c |
| 145 | \& members in an archive. |
| 146 | |
| 147 | The ordering of members in an archive can make a difference in how |
| 148 | programs are linked using the library, if a symbol is defined in more |
| 149 | than one member. |
| 150 | |
| 151 | If no modifiers are used with \c |
| 152 | .B m\c |
| 153 | \&, any members you name in the |
| 154 | \c |
| 155 | .I files\c |
| 156 | \& arguments are moved to the \c |
| 157 | .I end\c |
| 158 | \& of the archive; |
| 159 | you can use the `\|\c |
| 160 | .B a\c |
| 161 | \|', `\|\c |
| 162 | .B b\c |
| 163 | \|', or `\|\c |
| 164 | .B i\c |
| 165 | \|' modifiers to move them to a |
| 166 | specified place instead. |
| 167 | |
| 168 | .TP |
| 169 | .B p |
| 170 | \c |
| 171 | .I Print\c |
| 172 | \& the specified members of the archive, to the standard |
| 173 | output file. If the `\|\c |
| 174 | .B v\c |
| 175 | \|' modifier is specified, show the member |
| 176 | name before copying its contents to standard output. |
| 177 | |
| 178 | If you specify no \c |
| 179 | .I files\c |
| 180 | \&, all the files in the archive are printed. |
| 181 | |
| 182 | .TP |
| 183 | .B q |
| 184 | \c |
| 185 | .I Quick append\c |
| 186 | \&; add \c |
| 187 | .I files\c |
| 188 | \& to the end of \c |
| 189 | .I archive\c |
| 190 | \&, |
| 191 | without checking for replacement. |
| 192 | |
| 193 | The modifiers `\|\c |
| 194 | .B a\c |
| 195 | \|', `\|\c |
| 196 | .B b\c |
| 197 | \|', and `\|\c |
| 198 | .B i\c |
| 199 | \|' do \c |
| 200 | .I not\c |
| 201 | \& affect this |
| 202 | operation; new members are always placed at the end of the archive. |
| 203 | |
| 204 | The modifier `\|\c |
| 205 | .B v\c |
| 206 | \|' makes \c |
| 207 | .B ar\c |
| 208 | \& list each file as it is appended. |
| 209 | |
| 210 | Since the point of this operation is speed, the archive's symbol table |
| 211 | index is not updated, even if it already existed; you can use `\|\c |
| 212 | .B ar s\c |
| 213 | \|' or |
| 214 | \c |
| 215 | .B ranlib\c |
| 216 | \& explicitly to update the symbol table index. |
| 217 | |
| 218 | .TP |
| 219 | .B r |
| 220 | Insert \c |
| 221 | .I files\c |
| 222 | \& into \c |
| 223 | .I archive\c |
| 224 | \& (with \c |
| 225 | .I replacement\c |
| 226 | \&). This |
| 227 | operation differs from `\|\c |
| 228 | .B q\c |
| 229 | \|' in that any previously existing members |
| 230 | are deleted if their names match those being added. |
| 231 | |
| 232 | If one of the files named in \c |
| 233 | .I files\c |
| 234 | \& doesn't exist, \c |
| 235 | .B ar\c |
| 236 | \& |
| 237 | displays an error message, and leaves undisturbed any existing members |
| 238 | of the archive matching that name. |
| 239 | |
| 240 | By default, new members are added at the end of the file; but you may |
| 241 | use one of the modifiers `\|\c |
| 242 | .B a\c |
| 243 | \|', `\|\c |
| 244 | .B b\c |
| 245 | \|', or `\|\c |
| 246 | .B i\c |
| 247 | \|' to request |
| 248 | placement relative to some existing member. |
| 249 | |
| 250 | The modifier `\|\c |
| 251 | .B v\c |
| 252 | \|' used with this operation elicits a line of |
| 253 | output for each file inserted, along with one of the letters `\|\c |
| 254 | .B a\c |
| 255 | \|' or |
| 256 | `\|\c |
| 257 | .B r\c |
| 258 | \|' to indicate whether the file was appended (no old member |
| 259 | deleted) or replaced. |
| 260 | |
| 261 | .TP |
| 262 | .B t |
| 263 | Display a \c |
| 264 | .I table\c |
| 265 | \& listing the contents of \c |
| 266 | .I archive\c |
| 267 | \&, or those |
| 268 | of the files listed in \c |
| 269 | .I files\c |
| 270 | \& that are present in the |
| 271 | archive. Normally only the member name is shown; if you also want to |
| 272 | see the modes (permissions), timestamp, owner, group, and size, you can |
| 273 | request that by also specifying the `\|\c |
| 274 | .B v\c |
| 275 | \|' modifier. |
| 276 | |
| 277 | If you do not specify any \c |
| 278 | .I files\c |
| 279 | \&, all files in the archive |
| 280 | are listed. |
| 281 | |
| 282 | If there is more than one file with the same name (say, `\|\c |
| 283 | .B fie\c |
| 284 | \|') in |
| 285 | an archive (say `\|\c |
| 286 | .B b.a\c |
| 287 | \|'), `\|\c |
| 288 | .B ar t b.a fie\c |
| 289 | \|' will list only the |
| 290 | first instance; to see them all, you must ask for a complete |
| 291 | listing\(em\&in our example, `\|\c |
| 292 | .B ar t b.a\c |
| 293 | \|'. |
| 294 | |
| 295 | .TP |
| 296 | .B x |
| 297 | \c |
| 298 | .I Extract\c |
| 299 | \& members (named \c |
| 300 | .I files\c |
| 301 | \&) from the archive. You can |
| 302 | use the `\|\c |
| 303 | .B v\c |
| 304 | \|' modifier with this operation, to request that |
| 305 | \c |
| 306 | .B ar\c |
| 307 | \& list each name as it extracts it. |
| 308 | |
| 309 | If you do not specify any \c |
| 310 | .I files\c |
| 311 | \&, all files in the archive |
| 312 | are extracted. |
| 313 | |
| 314 | .PP |
| 315 | |
| 316 | A number of modifiers (\c |
| 317 | .I mod\c |
| 318 | \&) may immediately follow the \c |
| 319 | .I p\c |
| 320 | \& |
| 321 | keyletter, to specify variations on an operation's behavior: |
| 322 | |
| 323 | .TP |
| 324 | .B a |
| 325 | Add new files \c |
| 326 | .I after\c |
| 327 | \& an existing member of the |
| 328 | archive. If you use the modifier \c |
| 329 | .B a\c |
| 330 | \&, the name of an existing archive |
| 331 | member must be present as the \c |
| 332 | .I membername\c |
| 333 | \& argument, before the |
| 334 | \c |
| 335 | .I archive\c |
| 336 | \& specification. |
| 337 | |
| 338 | .TP |
| 339 | .B b |
| 340 | Add new files \c |
| 341 | .I before\c |
| 342 | \& an existing member of the |
| 343 | archive. If you use the modifier \c |
| 344 | .B b\c |
| 345 | \&, the name of an existing archive |
| 346 | member must be present as the \c |
| 347 | .I membername\c |
| 348 | \& argument, before the |
| 349 | \c |
| 350 | .I archive\c |
| 351 | \& specification. (same as `\|\c |
| 352 | .B i\c |
| 353 | \|'). |
| 354 | |
| 355 | .TP |
| 356 | .B c |
| 357 | \c |
| 358 | .I Create\c |
| 359 | \& the archive. The specified \c |
| 360 | .I archive\c |
| 361 | \& is always |
| 362 | created if it didn't exist, when you request an update. But a warning is |
| 363 | issued unless you specify in advance that you expect to create it, by |
| 364 | using this modifier. |
| 365 | |
| 366 | .TP |
| 367 | .B f |
| 368 | Truncate names in the archive. |
| 369 | .B ar |
| 370 | will normally permit file names of any length. This will cause it to |
| 371 | create archives which are not compatible with the native |
| 372 | .B ar |
| 373 | program on some systems. If this is a concern, the |
| 374 | .B f |
| 375 | modifier may be used to truncate file names when putting them in the |
| 376 | archive. |
| 377 | |
| 378 | .TP |
| 379 | .B i |
| 380 | Insert new files \c |
| 381 | .I before\c |
| 382 | \& an existing member of the |
| 383 | archive. If you use the modifier \c |
| 384 | .B i\c |
| 385 | \&, the name of an existing archive |
| 386 | member must be present as the \c |
| 387 | .I membername\c |
| 388 | \& argument, before the |
| 389 | \c |
| 390 | .I archive\c |
| 391 | \& specification. (same as `\|\c |
| 392 | .B b\c |
| 393 | \|'). |
| 394 | |
| 395 | .TP |
| 396 | .B l |
| 397 | This modifier is accepted but not used. |
| 398 | |
| 399 | .TP |
| 400 | .B o |
| 401 | Preserve the \c |
| 402 | .I original\c |
| 403 | \& dates of members when extracting them. If |
| 404 | you do not specify this modifier, files extracted from the archive |
| 405 | will be stamped with the time of extraction. |
| 406 | |
| 407 | .TP |
| 408 | .B s |
| 409 | Write an object-file index into the archive, or update an existing one, |
| 410 | even if no other change is made to the archive. You may use this modifier |
| 411 | flag either with any operation, or alone. Running `\|\c |
| 412 | .B ar s\c |
| 413 | \|' on an |
| 414 | archive is equivalent to running `\|\c |
| 415 | .B ranlib\c |
| 416 | \|' on it. |
| 417 | |
| 418 | .TP |
| 419 | .B u |
| 420 | Normally, \c |
| 421 | .B ar r\c |
| 422 | \&.\|.\|. inserts all files |
| 423 | listed into the archive. If you would like to insert \c |
| 424 | .I only\c |
| 425 | \& those |
| 426 | of the files you list that are newer than existing members of the same |
| 427 | names, use this modifier. The `\|\c |
| 428 | .B u\c |
| 429 | \|' modifier is allowed only for the |
| 430 | operation `\|\c |
| 431 | .B r\c |
| 432 | \|' (replace). In particular, the combination `\|\c |
| 433 | .B qu\c |
| 434 | \|' is |
| 435 | not allowed, since checking the timestamps would lose any speed |
| 436 | advantage from the operation `\|\c |
| 437 | .B q\c |
| 438 | \|'. |
| 439 | |
| 440 | .TP |
| 441 | .B v |
| 442 | This modifier requests the \c |
| 443 | .I verbose\c |
| 444 | \& version of an operation. Many |
| 445 | operations display additional information, such as filenames processed, |
| 446 | when the modifier `\|\c |
| 447 | .B v\c |
| 448 | \|' is appended. |
| 449 | |
| 450 | .TP |
| 451 | .B V |
| 452 | This modifier shows the version number of |
| 453 | .BR ar . |
| 454 | |
| 455 | .PP |
| 456 | |
| 457 | .SH "SEE ALSO" |
| 458 | .RB "`\|" binutils "\|'" |
| 459 | entry in |
| 460 | .B |
| 461 | info\c |
| 462 | \&; |
| 463 | .I |
| 464 | The GNU Binary Utilities\c |
| 465 | , Roland H. Pesch (October 1991). |
| 466 | .BR nm ( 1 )\c |
| 467 | \&, |
| 468 | .BR ranlib ( 1 )\c |
| 469 | \&. |
| 470 | |
| 471 | .SH COPYING |
| 472 | Copyright (c) 1991 Free Software Foundation, Inc. |
| 473 | .PP |
| 474 | Permission is granted to make and distribute verbatim copies of |
| 475 | this manual provided the copyright notice and this permission notice |
| 476 | are preserved on all copies. |
| 477 | .PP |
| 478 | Permission is granted to copy and distribute modified versions of this |
| 479 | manual under the conditions for verbatim copying, provided that the |
| 480 | entire resulting derived work is distributed under the terms of a |
| 481 | permission notice identical to this one. |
| 482 | .PP |
| 483 | Permission is granted to copy and distribute translations of this |
| 484 | manual into another language, under the above conditions for modified |
| 485 | versions, except that this permission notice may be included in |
| 486 | translations approved by the Free Software Foundation instead of in |
| 487 | the original English. |