contrib/binutils-2.15/binutils/doc/ar.1

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