binutils/ar.1

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