binutils/ar.1

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