1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\"  Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   4 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
   7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
   8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   9 .\"  This notice shall appear on any product containing this material.
  10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
  11 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
  12 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  13 .TH AR 1 "Aug 24, 2009"
  14 .SH NAME
  15 ar \- maintain portable archive or library
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 \fB/usr/bin/ar\fR \fB-d\fR [\fB-Vv\fR] \fIarchive\fR \fIfile\fR...
  20 .fi
  21 
  22 .LP
  23 .nf
  24 \fB/usr/bin/ar\fR \fB-m\fR [\fB-abiVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fB/usr/bin/ar\fR \fB-p\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fB/usr/bin/ar\fR \fB-q\fR [\fB-cVv\fR] \fIarchive\fR \fIfile\fR...
  35 .fi
  36 
  37 .LP
  38 .nf
  39 \fB/usr/bin/ar\fR \fB-r\fR [\fB-abciuVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
  40 .fi
  41 
  42 .LP
  43 .nf
  44 \fB/usr/bin/ar\fR \fB-t\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
  45 .fi
  46 
  47 .LP
  48 .nf
  49 \fB/usr/bin/ar\fR \fB-x\fR [\fB-CsTVv\fR] \fIarchive\fR [\fIfile\fR]...
  50 .fi
  51 
  52 .LP
  53 .nf
  54 \fB/usr/xpg4/bin/ar\fR \fB-d\fR [\fB-Vv\fR] \fIarchive\fR \fIfile\fR...
  55 .fi
  56 
  57 .LP
  58 .nf
  59 \fB/usr/xpg4/bin/ar\fR \fB-m\fR [\fB-abiVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
  60 .fi
  61 
  62 .LP
  63 .nf
  64 \fB/usr/xpg4/bin/ar\fR \fB-p\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
  65 .fi
  66 
  67 .LP
  68 .nf
  69 \fB/usr/xpg4/bin/ar\fR \fB-q\fR [\fB-cVv\fR] \fIarchive\fR \fIfile\fR...
  70 .fi
  71 
  72 .LP
  73 .nf
  74 \fB/usr/xpg4/bin/ar\fR \fB-r\fR [\fB-abciuVv\fR] [\fIposname\fR] \fIarchive\fR \fIfile\fR...
  75 .fi
  76 
  77 .LP
  78 .nf
  79 \fB/usr/xpg4/bin/ar\fR \fB-t\fR [\fB-sVv\fR] \fIarchive\fR [\fIfile\fR]...
  80 .fi
  81 
  82 .LP
  83 .nf
  84 \fB/usr/xpg4/bin/ar\fR \fB-x\fR [\fB-CsTVv\fR] \fIarchive\fR [\fIfile\fR]...
  85 .fi
  86 
  87 .SH DESCRIPTION
  88 .sp
  89 .LP
  90 The \fBar\fR utility maintains groups of files combined into a single archive
  91 file. Its main use is to create and update library files. However, it can be
  92 used for any similar purpose. The magic string and the file headers used by
  93 \fBar\fR consist of printable \fBASCII\fR characters. If an archive is composed
  94 of printable files, the entire archive is printable.
  95 .sp
  96 .LP
  97 When \fBar\fR creates an archive, it creates headers in a format that is
  98 portable across all machines. The portable archive format and structure are
  99 described in detail in \fBar.h\fR(3HEAD). The archive symbol table described
 100 there is used by the link editor \fBld\fR(1) to effect multiple passes over
 101 libraries of object files in an efficient manner. An archive symbol table is
 102 only created and maintained by \fBar\fR when there is at least one object file
 103 in the archive. The archive symbol table is in a specially named file that is
 104 always the first file in the archive. This file is never mentioned or
 105 accessible to the user. Whenever the \fBar\fR command is used to create or
 106 update the contents of such an archive, the symbol table is rebuilt. The
 107 \fB-s\fR option described below forces the symbol table to be rebuilt.
 108 .SH OPTIONS
 109 .sp
 110 .LP
 111 The following options are supported:
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fB-a\fR\fR
 116 .ad
 117 .RS 6n
 118 Positions new \fIfile\fRs in \fIarchive\fR after the file named by the
 119 \fIposname\fR operand.
 120 .RE
 121 
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fB-b\fR\fR
 126 .ad
 127 .RS 6n
 128 Positions new \fIfile\fRs in \fIarchive\fR before the file named by the
 129 \fIposname\fR operand.
 130 .RE
 131 
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB-c\fR\fR
 136 .ad
 137 .RS 6n
 138 Suppresses the diagnostic message that is written to standard error by default
 139 when \fIarchive\fR is created.
 140 .RE
 141 
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fB-C\fR\fR
 146 .ad
 147 .RS 6n
 148 Prevents extracted files from replacing like-named files in the file system.
 149 This option is useful when \fB-T\fR is also used to prevent truncated file
 150 names from replacing files with the same prefix.
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fB-d\fR\fR
 157 .ad
 158 .RS 6n
 159 Deletes one or more \fIfile\fRs from \fIarchive\fR.
 160 .RE
 161 
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fB-i\fR\fR
 166 .ad
 167 .RS 6n
 168 Positions new \fIfile\fRs in \fIarchive\fR before the file named by the
 169 \fIposname\fR operand. This option is quivalent to \fB-b\fR.
 170 .RE
 171 
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB-m\fR\fR
 176 .ad
 177 .RS 6n
 178 Moves \fIfile\fRs. If \fB-a\fR, \fB-b\fR, or \fB-i\fR with the \fIposname\fR
 179 operand are specified, the \fB-m\fR option moves \fIfile\fRs to the new
 180 position. Otherwise, \fB-m\fR moves \fIfile\fRs to the end of \fIarchive\fR.
 181 .RE
 182 
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fB-p\fR\fR
 187 .ad
 188 .RS 6n
 189 Prints the contents of \fIfile\fRs in \fIarchive\fR to standard output. If no
 190 \fIfile\fRs are specified, the contents of all files in \fIarchive\fR are
 191 written in the order of the archive.
 192 .RE
 193 
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fB-q\fR\fR
 198 .ad
 199 .RS 6n
 200 Quickly appends \fIfile\fRs to the end of \fIarchive\fR. Positioning options
 201 \fB-a\fR, \fB-b\fR, and \fB-i\fR are invalid. The command does not check
 202 whether the added \fIfile\fRs are already in \fIarchive\fR. This option is
 203 useful to avoid quadratic behavior when creating a large archive
 204 piece-by-piece.
 205 .RE
 206 
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fB-r\fR\fR
 211 .ad
 212 .RS 6n
 213 Replaces or adds \fIfile\fRs in \fIarchive\fR. If \fIarchive\fR does not exist,
 214 a new archive file is created and a diagnostic message is written to standard
 215 error, unless the \fB-c\fR option is specified. If no \fIfile\fRs are specified
 216 and the \fIarchive\fR exists, the results are undefined. Files that replace
 217 existing files do not change the order of the archive. If the \fB-u\fR option
 218 is used with the \fB-r\fR option, only those files with dates of modification
 219 later than the archive files are replaced. If the \fB-a\fR, \fB-b\fR, or
 220 \fB-i\fR option is used, the \fIposname\fR argument must be present and
 221 specifies that new files are to be placed after (\fB-a\fR) or before (\fB-b\fR
 222 or \fB-i\fR) \fIposname\fR. Otherwise, the new files are placed at the end.
 223 .RE
 224 
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fB-s\fR\fR
 229 .ad
 230 .RS 6n
 231 Forces the regeneration of the archive symbol table even if \fBar\fR is not
 232 invoked with an option that will modify the archive contents. This command is
 233 useful to restore the archive symbol table after the \fBstrip\fR(1) command has
 234 been used on the archive.
 235 .RE
 236 
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fB-t\fR\fR
 241 .ad
 242 .RS 6n
 243 Prints a table of contents of \fIarchive\fR. The files specified by the
 244 \fIfile\fR operands are included in the written list. If no \fIfile\fR operands
 245 are specified, all files in \fIarchive\fR are included in the order of the
 246 archive.
 247 .RE
 248 
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fB-T\fR\fR
 253 .ad
 254 .RS 6n
 255 Allows file name truncation of extracted files whose archive names are longer
 256 than the file system can support. By default, extracting a file with a name
 257 that is too long is an error. In that case, a diagnostic message is written and
 258 the file is not extracted.
 259 .RE
 260 
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fB-u\fR\fR
 265 .ad
 266 .RS 6n
 267 Updates older files. When used with the \fB-r\fR option, files within
 268 \fIarchive\fR are replaced only if the corresponding \fIfile\fR has a
 269 modification time that is at least as new as the modification time of the file
 270 within \fIarchive\fR.
 271 .RE
 272 
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fB-v\fR\fR
 277 .ad
 278 .RS 6n
 279 Gives verbose output. When used with options \fB-d\fR, \fB-r\fR, or \fB-x\fR,
 280 the \fB-v\fR option writes a detailed file-by-file description of the archive
 281 creation and the constituent \fIfile\fRs, and maintenance activity. When used
 282 with \fB-p\fR, \fB-v\fR writes the name of the file to the standard output
 283 before writing the file itself to the standard output. When used with \fB-t\fR,
 284 \fB-v\fR includes a long listing of information about the files within the
 285 archive. When used with \fB-x\fR, \fB-v\fR prints the filename preceding each
 286 extraction. When writing to an archive, \fB-v\fR writes a message to the
 287 standard error.
 288 .RE
 289 
 290 .sp
 291 .ne 2
 292 .na
 293 \fB\fB-V\fR\fR
 294 .ad
 295 .RS 6n
 296 Prints its version number on standard error.
 297 .RE
 298 
 299 .SS "\fB/usr/xpg4/bin/ar\fR"
 300 .sp
 301 .LP
 302 The following options are supported for \fB/usr/xpg4/bin/ar\fR:
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fB-v\fR\fR
 307 .ad
 308 .RS 6n
 309 Same as the \fB/usr/bin/ar\fR version, except when writing to an archive, no
 310 message is written to the standard error.
 311 .RE
 312 
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fB-x\fR\fR
 317 .ad
 318 .RS 6n
 319 Extracts the files named by the \fIfile\fR operands from \fIarchive\fR. The
 320 contents of \fIarchive\fR are not changed. If no \fIfile\fR operands are given,
 321 all files in \fIarchive\fR are extracted. If the file name of a file extracted
 322 from \fIarchive\fR is longer than that supported in the directory to which it
 323 is being extracted, the results are undefined. The modification time of each
 324 \fIfile\fR extracted is set to the time \fIfile\fR is extracted from
 325 \fIarchive\fR.
 326 .RE
 327 
 328 .SH OPERANDS
 329 .sp
 330 .LP
 331 The following operands are supported:
 332 .sp
 333 .ne 2
 334 .na
 335 \fB\fIarchive\fR\fR
 336 .ad
 337 .RS 11n
 338 A path name of the archive file.
 339 .RE
 340 
 341 .sp
 342 .ne 2
 343 .na
 344 \fB\fIfile\fR\fR
 345 .ad
 346 .RS 11n
 347 A path name. Only the last component is used when comparing against the names
 348 of files in the archive. If two or more \fIfile\fR operands have the same last
 349 path name component (see \fBbasename\fR(1)), the results are unspecified. The
 350 implementation's archive format will not truncate valid file names of files
 351 added to or replaced in the archive.
 352 .RE
 353 
 354 .sp
 355 .ne 2
 356 .na
 357 \fB\fIposname\fR\fR
 358 .ad
 359 .RS 11n
 360 The name of a file in the archive file, used for relative positioning. See
 361 options \fB-m\fR and \fB-r\fR.
 362 .RE
 363 
 364 .SH ENVIRONMENT VARIABLES
 365 .sp
 366 .LP
 367 See \fBenviron\fR(5) for descriptions of the following environment variables
 368 that affect the execution of \fBar\fR: \fBLANG\fR, \fBLC_ALL\fR,
 369 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBLC_TIME\fR, and \fBNLSPATH\fR.
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fBTMPDIR\fR\fR
 374 .ad
 375 .RS 10n
 376 Determine the pathname that overrides the default directory for temporary
 377 files, if any.
 378 .RE
 379 
 380 .sp
 381 .ne 2
 382 .na
 383 \fB\fBTZ\fR\fR
 384 .ad
 385 .RS 10n
 386 Determine the timezone used to calculate date and time strings written by
 387 \fBar\fR \fB-tv\fR. If \fBTZ\fR is unset or null, an unspecified default
 388 timezone is used.
 389 .RE
 390 
 391 .SH EXIT STATUS
 392 .sp
 393 .LP
 394 The following exit values are returned:
 395 .sp
 396 .ne 2
 397 .na
 398 \fB\fB0\fR\fR
 399 .ad
 400 .RS 6n
 401 Successful completion.
 402 .RE
 403 
 404 .sp
 405 .ne 2
 406 .na
 407 \fB\fB>0\fR\fR
 408 .ad
 409 .RS 6n
 410 An error occurred.
 411 .RE
 412 
 413 .SH ATTRIBUTES
 414 .sp
 415 .LP
 416 See \fBattributes\fR(5) for descriptions of the following attributes:
 417 .SS "\fB/usr/bin/ar\fR"
 418 .sp
 419 
 420 .sp
 421 .TS
 422 box;
 423 c | c
 424 l | l .
 425 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 426 _
 427 Interface Stability     Committed
 428 .TE
 429 
 430 .SS "\fB/usr/xpg4/bin/ar\fR"
 431 .sp
 432 
 433 .sp
 434 .TS
 435 box;
 436 c | c
 437 l | l .
 438 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 439 _
 440 Interface Stability     Committed
 441 _
 442 Standard        See \fBstandards\fR(5).
 443 .TE
 444 
 445 .SH SEE ALSO
 446 .sp
 447 .LP
 448 \fBbasename\fR(1), \fBcpio\fR(1), \fBld\fR(1), \fBlorder\fR(1), \fBstrip\fR(1),
 449 \fBtar\fR(1), \fBar.h\fR(3HEAD), \fBa.out\fR(4), \fBattributes\fR(5),
 450 \fBenviron\fR(5), \fBstandards\fR(5)
 451 .SH NOTES
 452 .sp
 453 .LP
 454 If the same file is mentioned twice in an argument list, it may be put in the
 455 archive twice.
 456 .sp
 457 .LP
 458 By convention, archives are suffixed with "\fB\&.a\fR".
 459 .sp
 460 .LP
 461 When inserting \fBELF\fR objects into an archive file, \fBar\fR might add
 462 "\fB\n\fR" characters to pad these objects to an 8-byte boundary. Such padding
 463 improves the efficiency with which \fBld\fR(1) can access the archive. Only
 464 \fBELF\fR object files are padded in this way. Other archive members are not
 465 altered. When an object with such padding is extracted from an archive, the
 466 padding is not included in the resulting output.