gnu/usr.bin/binutils/ar/ar.1

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