contrib/binutils/binutils/doc/ar.1

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