binutils/ar.1

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 ''' Revision 1.7  2001/03/25 20:32:25  nickc
   6 ''' Automate generate on man pages
   7 '''
   8 '''
   9 .de Sh
  10 .br
  11 .if t .Sp
  12 .ne 5
  13 .PP
  14 \fB\\$1\fR
  15 .PP
  16 ..
  17 .de Sp
  18 .if t .sp .5v
  19 .if n .sp
  20 ..
  21 .de Ip
  22 .br
  23 .ie \\n(.$>=3 .ne \\$3
  24 .el .ne 3
  25 .IP "\\$1" \\$2
  26 ..
  27 .de Vb
  28 .ft CW
  29 .nf
  30 .ne \\$1
  31 ..
  32 .de Ve
  33 .ft R
  34
  35 .fi
  36 ..
  37 '''
  38 '''
  39 '''     Set up \*(-- to give an unbreakable dash;
  40 '''     string Tr holds user defined translation string.
  41 '''     Bell System Logo is used as a dummy character.
  42 '''
  43 .tr \(*W-|\(bv\*(Tr
  44 .ie n \{\
  45 .ds -- \(*W-
  46 .ds PI pi
  47 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  48 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  49 .ds L" ""
  50 .ds R" ""
  51 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  52 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  53 '''   such as .IP and .SH, which do another additional levels of
  54 '''   double-quote interpretation
  55 .ds M" """
  56 .ds S" """
  57 .ds N" """""
  58 .ds T" """""
  59 .ds L' '
  60 .ds R' '
  61 .ds M' '
  62 .ds S' '
  63 .ds N' '
  64 .ds T' '
  65 'br\}
  66 .el\{\
  67 .ds -- \(em\|
  68 .tr \*(Tr
  69 .ds L" ``
  70 .ds R" ''
  71 .ds M" ``
  72 .ds S" ''
  73 .ds N" ``
  74 .ds T" ''
  75 .ds L' `
  76 .ds R' '
  77 .ds M' `
  78 .ds S' '
  79 .ds N' `
  80 .ds T' '
  81 .ds PI \(*p
  82 'br\}
  83 .\"     If the F register is turned on, we'll generate
  84 .\"     index entries out stderr for the following things:
  85 .\"             TH      Title
  86 .\"             SH      Header
  87 .\"             Sh      Subsection
  88 .\"             Ip      Item
  89 .\"             X<>     Xref  (embedded
  90 .\"     Of course, you have to process the output yourself
  91 .\"     in some meaninful fashion.
  92 .if \nF \{
  93 .de IX
  94 .tm Index:\\$1\t\\n%\t"\\$2"
  95 ..
  96 .nr % 0
  97 .rr F
  98 .\}
  99 .TH AR.1 1 "binutils-2.11.90" "23/Mar/101" "GNU"
 100 .UC
 101 .if n .hy 0
 102 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 103 .de CQ          \" put $1 in typewriter font
 104 .ft CW
 105 'if n "\c
 106 'if t \\&\\$1\c
 107 'if n \\&\\$1\c
 108 'if n \&"
 109 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 110 '.ft R
 111 ..
 112 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 113 .       \" AM - accent mark definitions
 114 .bd B 3
 115 .       \" fudge factors for nroff and troff
 116 .if n \{\
 117 .       ds #H 0
 118 .       ds #V .8m
 119 .       ds #F .3m
 120 .       ds #[ \f1
 121 .       ds #] \fP
 122 .\}
 123 .if t \{\
 124 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 125 .       ds #V .6m
 126 .       ds #F 0
 127 .       ds #[ \&
 128 .       ds #] \&
 129 .\}
 130 .       \" simple accents for nroff and troff
 131 .if n \{\
 132 .       ds ' \&
 133 .       ds ` \&
 134 .       ds ^ \&
 135 .       ds , \&
 136 .       ds ~ ~
 137 .       ds ? ?
 138 .       ds ! !
 139 .       ds /
 140 .       ds q
 141 .\}
 142 .if t \{\
 143 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 144 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 145 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 146 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 147 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 148 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 149 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 150 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 151 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 152 .\}
 153 .       \" troff and (daisy-wheel) nroff accents
 154 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 155 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 156 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 157 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 158 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 159 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 160 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 161 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 162 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 163 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 164 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 165 .ds ae a\h'-(\w'a'u*4/10)'e
 166 .ds Ae A\h'-(\w'A'u*4/10)'E
 167 .ds oe o\h'-(\w'o'u*4/10)'e
 168 .ds Oe O\h'-(\w'O'u*4/10)'E
 169 .       \" corrections for vroff
 170 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 171 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 172 .       \" for low resolution devices (crt and lpr)
 173 .if \n(.H>23 .if \n(.V>19 \
 174 \{\
 175 .       ds : e
 176 .       ds 8 ss
 177 .       ds v \h'-1'\o'\(aa\(ga'
 178 .       ds _ \h'-1'^
 179 .       ds . \h'-1'.
 180 .       ds 3 3
 181 .       ds o a
 182 .       ds d- d\h'-1'\(ga
 183 .       ds D- D\h'-1'\(hy
 184 .       ds th \o'bp'
 185 .       ds Th \o'LP'
 186 .       ds ae ae
 187 .       ds Ae AE
 188 .       ds oe oe
 189 .       ds Oe OE
 190 .\}
 191 .rm #[ #] #H #V #F C
 192 .SH "NAME"
 193 ar \- create, modify, and extract from archives
 194 .SH "SYNOPSIS"
 195 ar [\-X32_64] [\-]\fIp\fR[\fImod\fR [\fIrelpos\fR] [\fIcount\fR]] \fIarchive\fR [\fImember\fR...]
 196 .SH "DESCRIPTION"
 197 The GNU \f(CWar\fR program creates, modifies, and extracts from
 198 archives.  An \fIarchive\fR is a single file holding a collection of
 199 other files in a structure that makes it possible to retrieve
 200 the original individual files (called \fImembers\fR of the archive).
 201 .PP
 202 The original files\*(R' contents, mode (permissions), timestamp, owner, and
 203 group are preserved in the archive, and can be restored on
 204 extraction.
 205 .PP
 206 GNU \f(CWar\fR can maintain archives whose members have names of any
 207 length; however, depending on how \f(CWar\fR is configured on your
 208 system, a limit on member-name length may be imposed for compatibility
 209 with archive formats maintained with other tools.  If it exists, the
 210 limit is often 15 characters (typical of formats related to a.out) or 16
 211 characters (typical of formats related to coff).
 212 .PP
 213 \f(CWar\fR is considered a binary utility because archives of this sort
 214 are most often used as \fIlibraries\fR holding commonly needed
 215 subroutines.
 216 .PP
 217 \f(CWar\fR creates an index to the symbols defined in relocatable
 218 object modules in the archive when you specify the modifier \fBs\fR.
 219 Once created, this index is updated in the archive whenever \f(CWar\fR
 220 makes a change to its contents (save for the \fBq\fR update operation).
 221 An archive with such an index speeds up linking to the library, and
 222 allows routines in the library to call each other without regard to
 223 their placement in the archive.
 224 .PP
 225 You may use \fBnm \-s\fR or \fBnm --print-armap\fR to list this index
 226 table.  If an archive lacks the table, another form of \f(CWar\fR called
 227 \f(CWranlib\fR can be used to add just the table.
 228 .PP
 229 GNU \f(CWar\fR is designed to be compatible with two different
 230 facilities.  You can control its activity using command-line options,
 231 like the different varieties of \f(CWar\fR on Unix systems; or, if you
 232 specify the single command-line option \fB\-M\fR, you can control it
 233 with a script supplied via standard input, like the MRI ``librarian'\*(R'
 234 program.
 235 .SH "OPTIONS"
 236 GNU \f(CWar\fR allows you to mix the operation code \fIp\fR and modifier
 237 flags \fImod\fR in any order, within the first command-line argument.
 238 .PP
 239 If you wish, you may begin the first command-line argument with a
 240 dash.
 241 .PP
 242 The \fIp\fR keyletter specifies what operation to execute; it may be
 243 any of the following, but you must specify only one of them:
 244 .Ip "\f(CWd\fR" 4
 245 \fIDelete\fR modules from the archive.  Specify the names of modules to
 246 be deleted as \fImember\fR...; the archive is untouched if you
 247 specify no files to delete.
 248 .Sp
 249 If you specify the \fBv\fR modifier, \f(CWar\fR lists each module
 250 as it is deleted.
 251 .Ip "\f(CWm\fR" 4
 252 Use this operation to \fImove\fR members in an archive.
 253 .Sp
 254 The ordering of members in an archive can make a difference in how
 255 programs are linked using the library, if a symbol is defined in more
 256 than one member.
 257 .Sp
 258 If no modifiers are used with \f(CWm\fR, any members you name in the
 259 \fImember\fR arguments are moved to the \fIend\fR of the archive;
 260 you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a
 261 specified place instead.
 262 .Ip "\f(CWp\fR" 4
 263 \fIPrint\fR the specified members of the archive, to the standard
 264 output file.  If the \fBv\fR modifier is specified, show the member
 265 name before copying its contents to standard output.
 266 .Sp
 267 If you specify no \fImember\fR arguments, all the files in the archive are
 268 printed.
 269 .Ip "\f(CWq\fR" 4
 270 \fIQuick append\fR; Historically, add the files \fImember\fR... to the end of
 271 \fIarchive\fR, without checking for replacement.
 272 .Sp
 273 The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this
 274 operation; new members are always placed at the end of the archive.
 275 .Sp
 276 The modifier \fBv\fR makes \f(CWar\fR list each file as it is appended.
 277 .Sp
 278 Since the point of this operation is speed, the archive's symbol table
 279 index is not updated, even if it already existed; you can use \fBar s\fR or
 280 \f(CWranlib\fR explicitly to update the symbol table index.
 281 .Sp
 282 However, too many different systems assume quick append rebuilds the
 283 index, so \s-1GNU\s0 ar implements \f(CWq\fR as a synonym for \f(CWr\fR.
 284 .Ip "\f(CWr\fR" 4
 285 Insert the files \fImember\fR... into \fIarchive\fR (with
 286 \fIreplacement\fR). This operation differs from \fBq\fR in that any
 287 previously existing members are deleted if their names match those being
 288 added.
 289 .Sp
 290 If one of the files named in \fImember\fR... does not exist, \f(CWar\fR
 291 displays an error message, and leaves undisturbed any existing members
 292 of the archive matching that name.
 293 .Sp
 294 By default, new members are added at the end of the file; but you may
 295 use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request
 296 placement relative to some existing member.
 297 .Sp
 298 The modifier \fBv\fR used with this operation elicits a line of
 299 output for each file inserted, along with one of the letters \fBa\fR or
 300 \fBr\fR to indicate whether the file was appended (no old member
 301 deleted) or replaced.
 302 .Ip "\f(CWt\fR" 4
 303 Display a \fItable\fR listing the contents of \fIarchive\fR, or those
 304 of the files listed in \fImember\fR... that are present in the
 305 archive.  Normally only the member name is shown; if you also want to
 306 see the modes (permissions), timestamp, owner, group, and size, you can
 307 request that by also specifying the \fBv\fR modifier.
 308 .Sp
 309 If you do not specify a \fImember\fR, all files in the archive
 310 are listed.
 311 .Sp
 312 If there is more than one file with the same name (say, \fBfie\fR) in
 313 an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the
 314 first instance; to see them all, you must ask for a complete
 315 listing---in our example, \fBar t b.a\fR.
 316 .Ip "\f(CWx\fR" 4
 317 \fIExtract\fR members (named \fImember\fR) from the archive.  You can
 318 use the \fBv\fR modifier with this operation, to request that
 319 \f(CWar\fR list each name as it extracts it.
 320 .Sp
 321 If you do not specify a \fImember\fR, all files in the archive
 322 are extracted.
 323 .PP
 324 A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR
 325 keyletter, to specify variations on an operation's behavior:
 326 .Ip "\f(CWa\fR" 4
 327 Add new files \fIafter\fR an existing member of the
 328 archive.  If you use the modifier \fBa\fR, the name of an existing archive
 329 member must be present as the \fIrelpos\fR argument, before the
 330 \fIarchive\fR specification.
 331 .Ip "\f(CWb\fR" 4
 332 Add new files \fIbefore\fR an existing member of the
 333 archive.  If you use the modifier \fBb\fR, the name of an existing archive
 334 member must be present as the \fIrelpos\fR argument, before the
 335 \fIarchive\fR specification.  (same as \fBi\fR).
 336 .Ip "\f(CWc\fR" 4
 337 \fICreate\fR the archive.  The specified \fIarchive\fR is always
 338 created if it did not exist, when you request an update.  But a warning is
 339 issued unless you specify in advance that you expect to create it, by
 340 using this modifier.
 341 .Ip "\f(CWf\fR" 4
 342 Truncate names in the archive.  \s-1GNU\s0 \f(CWar\fR will normally permit file
 343 names of any length.  This will cause it to create archives which are
 344 not compatible with the native \f(CWar\fR program on some systems.  If
 345 this is a concern, the \fBf\fR modifier may be used to truncate file
 346 names when putting them in the archive.
 347 .Ip "\f(CWi\fR" 4
 348 Insert new files \fIbefore\fR an existing member of the
 349 archive.  If you use the modifier \fBi\fR, the name of an existing archive
 350 member must be present as the \fIrelpos\fR argument, before the
 351 \fIarchive\fR specification.  (same as \fBb\fR).
 352 .Ip "\f(CWl\fR" 4
 353 This modifier is accepted but not used.
 354 .Ip "\f(CWN\fR" 4
 355 Uses the \fIcount\fR parameter.  This is used if there are multiple
 356 entries in the archive with the same name.  Extract or delete instance
 357 \fIcount\fR of the given name from the archive.
 358 .Ip "\f(CWo\fR" 4
 359 Preserve the \fIoriginal\fR dates of members when extracting them.  If
 360 you do not specify this modifier, files extracted from the archive
 361 are stamped with the time of extraction.
 362 .Ip "\f(CWP\fR" 4
 363 Use the full path name when matching names in the archive.  \s-1GNU\s0
 364 \f(CWar\fR can not create an archive with a full path name (such archives
 365 are not \s-1POSIX\s0 complaint), but other archive creators can.  This option
 366 will cause \s-1GNU\s0 \f(CWar\fR to match file names using a complete path
 367 name, which can be convenient when extracting a single file from an
 368 archive created by another tool.
 369 .Ip "\f(CWs\fR" 4
 370 Write an object-file index into the archive, or update an existing one,
 371 even if no other change is made to the archive.  You may use this modifier
 372 flag either with any operation, or alone.  Running \fBar s\fR on an
 373 archive is equivalent to running \fBranlib\fR on it.
 374 .Ip "\f(CWS\fR" 4
 375 Do not generate an archive symbol table.  This can speed up building a
 376 large library in several steps.  The resulting archive can not be used
 377 with the linker.  In order to build a symbol table, you must omit the
 378 \fBS\fR modifier on the last execution of \fBar\fR, or you must run
 379 \fBranlib\fR on the archive.
 380 .Ip "\f(CWu\fR" 4
 381 Normally, \fBar r\fR... inserts all files
 382 listed into the archive.  If you would like to insert \fIonly\fR those
 383 of the files you list that are newer than existing members of the same
 384 names, use this modifier.  The \fBu\fR modifier is allowed only for the
 385 operation \fBr\fR (replace).  In particular, the combination \fBqu\fR is
 386 not allowed, since checking the timestamps would lose any speed
 387 advantage from the operation \fBq\fR.
 388 .Ip "\f(CWv\fR" 4
 389 This modifier requests the \fIverbose\fR version of an operation.  Many
 390 operations display additional information, such as filenames processed,
 391 when the modifier \fBv\fR is appended.
 392 .Ip "\f(CWV\fR" 4
 393 This modifier shows the version number of \f(CWar\fR.
 394 .PP
 395 \f(CWar\fR ignores an initial option spelt \f(CW-X32_64\fR, for
 396 compatibility with \s-1AIX\s0.  The behaviour produced by this option is the
 397 default for \s-1GNU\s0 \f(CWar\fR.  \f(CWar\fR does not support any of the other
 398 \f(CW-X\fR options; in particular, it does not support \f(CW-X32\fR
 399 which is the default for \s-1AIX\s0 \f(CWar\fR.
 400 .SH "SEE ALSO"
 401 \fInm\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
 402 .SH "COPYRIGHT"
 403 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
 404 .PP
 405 Permission is granted to copy, distribute and/or modify this document
 406 under the terms of the GNU Free Documentation License, Version 1.1
 407 or any later version published by the Free Software Foundation;
 408 with no Invariant Sections, with no Front-Cover Texts, and with no
 409 Back-Cover Texts.  A copy of the license is included in the
 410 section entitled \*(L"GNU Free Documentation License\*(R".
 411
 412 .rn }` ''
 413 .IX Title "AR.1 1"
 414 .IX Name "ar - create, modify, and extract from archives"
 415
 416 .IX Header "NAME"
 417
 418 .IX Header "SYNOPSIS"
 419
 420 .IX Header "DESCRIPTION"
 421
 422 .IX Header "OPTIONS"
 423
 424 .IX Item "\f(CWd\fR"
 425
 426 .IX Item "\f(CWm\fR"
 427
 428 .IX Item "\f(CWp\fR"
 429
 430 .IX Item "\f(CWq\fR"
 431
 432 .IX Item "\f(CWr\fR"
 433
 434 .IX Item "\f(CWt\fR"
 435
 436 .IX Item "\f(CWx\fR"
 437
 438 .IX Item "\f(CWa\fR"
 439
 440 .IX Item "\f(CWb\fR"
 441
 442 .IX Item "\f(CWc\fR"
 443
 444 .IX Item "\f(CWf\fR"
 445
 446 .IX Item "\f(CWi\fR"
 447
 448 .IX Item "\f(CWl\fR"
 449
 450 .IX Item "\f(CWN\fR"
 451
 452 .IX Item "\f(CWo\fR"
 453
 454 .IX Item "\f(CWP\fR"
 455
 456 .IX Item "\f(CWs\fR"
 457
 458 .IX Item "\f(CWS\fR"
 459
 460 .IX Item "\f(CWu\fR"
 461
 462 .IX Item "\f(CWv\fR"
 463
 464 .IX Item "\f(CWV\fR"
 465
 466 .IX Header "SEE ALSO"
 467
 468 .IX Header "COPYRIGHT"
 469