usr.bin/ar/ar.1

   1 .\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Joseph Koshy ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd August 31, 2007
  27 .Os
  28 .Dt AR 1
  29 .Sh NAME
  30 .Nm ar ,
  31 .Nm ranlib
  32 .Nd manage archives
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Fl d
  36 .Op Fl T
  37 .Op Fl j
  38 .Op Fl v
  39 .Op Fl z
  40 .Ar archive
  41 .Ar files ...
  42 .Nm
  43 .Fl m
  44 .Op Fl T
  45 .Op Fl a Ar position-after
  46 .Op Fl b Ar position-before
  47 .Op Fl i Ar position-before
  48 .Op Fl j
  49 .Op Fl s
  50 .Op Fl z
  51 .Ar archive
  52 .Ar files ...
  53 .Nm
  54 .Fl p
  55 .Op Fl T
  56 .Op Fl v
  57 .Ar archive
  58 .Op Ar files ...
  59 .Nm
  60 .Fl r
  61 .Op Fl T
  62 .Op Fl a Ar position-after
  63 .Op Fl b Ar position-before
  64 .Op Fl c
  65 .Op Fl i Ar position-before
  66 .Op Fl j
  67 .Op Fl s
  68 .Op Fl u
  69 .Op Fl v
  70 .Op Fl z
  71 .Ar archive
  72 .Ar files ...
  73 .Nm
  74 .Fl s
  75 .Op Fl j
  76 .Op Fl z
  77 .Ar archive
  78 .Nm
  79 .Fl t
  80 .Op Fl T
  81 .Op Fl v
  82 .Ar archive
  83 .Op Ar files ...
  84 .Nm
  85 .Fl x
  86 .Op Fl C
  87 .Op Fl T
  88 .Op Fl o
  89 .Op Fl u
  90 .Op Fl v
  91 .Ar archive
  92 .Op Ar files ...
  93 .Nm ranlib
  94 .Ar archive ...
  95 .Sh DESCRIPTION
  96 The
  97 .Nm
  98 utility creates and maintains groups of files combined into an
  99 archive.
 100 Once an archive has been created, new files can be added to it, and
 101 existing files can be extracted, deleted or replaced.
 102 .Pp
 103 Files are named in the archive by their last file name component,
 104 so if a file referenced by a path containing a
 105 .Dq /
 106 is archived, it will be named by the last component of the path.
 107 Similarly when matching paths listed on the command line against
 108 file names stored in the archive, only the last component of the
 109 path will be compared.
 110 .Pp
 111 The normal use of
 112 .Nm
 113 is for the creation and maintenance of libraries suitable for use
 114 with the link editor
 115 .Xr ld 1 ,
 116 although it is not restricted to this purpose.
 117 The
 118 .Nm
 119 utility can create and manage an archive symbol table (see
 120 .Xr ar 5 )
 121 used to speed up link editing operations.
 122 If a symbol table is present in an archive, it will be
 123 kept up-to-date by subsequent operations on the archive (excepting
 124 the quick update specified by the
 125 .Fl q
 126 option).
 127 .Pp
 128 The
 129 .Nm ranlib
 130 utility is used to add an archive symbol table
 131 to an existing archive.
 132 .Sh OPTIONS
 133 The
 134 .Nm
 135 utility supports the following options:
 136 .Bl -tag -width indent
 137 .It Fl a Ar member-after
 138 When used with option
 139 .Fl m
 140 this option specifies that the archive members specified by
 141 arguments
 142 .Ar files ...
 143 are moved to after the archive member named by argument
 144 .Ar member-after .
 145 When used with option
 146 .Fl r
 147 this option specifies that the files specified by arguments
 148 .Ar files ...
 149 are added after the archive member named by argument
 150 .Ar member-after .
 151 .It Fl b Ar member-before
 152 When used with option
 153 .Fl m
 154 this option specifies that the archive members specified by
 155 arguments
 156 .Ar files ...
 157 are moved to before the archive member named by argument
 158 .Ar member-before .
 159 When used with option
 160 .Fl r
 161 this option specifies that the files specified by arguments
 162 .Ar files ...
 163 are added before the archive member named by argument
 164 .Ar member-before .
 165 .It Fl c
 166 Suppress the informational message printed when a new archive is
 167 created using the
 168 .Fl r
 169 and
 170 .Fl q
 171 options.
 172 .It Fl C
 173 Prevent extracted files from replacing like-named files
 174 in the file system.
 175 .It Fl d
 176 Delete the members named by arguments
 177 .Ar files ...
 178 from the archive specified by argument
 179 .Ar archive .
 180 The archive's symbol table, if present, is updated to reflect
 181 the new contents of the archive.
 182 .It Fl f
 183 Synonymous with option
 184 .Fl T .
 185 .It Fl i Ar member-before
 186 Synonymous with option
 187 .Fl b .
 188 .It Fl j
 189 Compress the resulting archive with
 190 .Xr bzip2 1 .
 191 .It Fl m
 192 Move archive members specified by arguments
 193 .Ar files ...
 194 within the archive.
 195 If a position has been specified by one of the
 196 .Fl a ,
 197 .Fl b
 198 or
 199 .Fl i
 200 options, the members are moved to before or after the specified
 201 position.
 202 If no position has been specified, the specified members are moved
 203 to the end of the archive.
 204 If the archive has a symbol table, it is updated to reflect the
 205 new contents of the archive.
 206 .It Fl o
 207 Preserve the original modification times of members when extracting
 208 them.
 209 .It Fl p
 210 Write the contents of the specified archive members named by
 211 arguments
 212 .Ar files ...
 213 to standard output.
 214 If no members were specified, the contents of all the files in the
 215 archive are written in the order they appear in the archive.
 216 .It Fl q
 217 Append the files specified by arguments
 218 .Ar files ...
 219 to the archive specified by argument
 220 .Ar archive
 221 without checking if the files already exist in the archive and
 222 without updating the archive's symbol table.
 223 If the archive file
 224 .Ar archive
 225 does not already exist, a new archive is created.
 226 However, to be compatible with GNU
 227 .Nm ,
 228 option
 229 .Fl q
 230 will update the archive's symbol table.
 231 .It Fl r
 232 Replace (add) the files specified by arguments
 233 .Ar files ...
 234 in the archive specified by argument
 235 .Ar archive ,
 236 creating the archive if necessary.
 237 Files that replace existing files do not change the order of files
 238 within the archive.
 239 If a file named in arguments
 240 .Ar files ...
 241 does not exist, existing members in the archive that match that
 242 name are not changed.
 243 New files are added to the end of the archive unless one of the
 244 positioning options
 245 .Fl a ,
 246 .Fl b
 247 or
 248 .Fl i
 249 is specified.
 250 The archive symbol table, if it exists, is updated to reflect the
 251 new state of the archive.
 252 .It Fl s
 253 Add an archive symbol table (see
 254 .Xr ar 5 )
 255 to the archive specified by argument
 256 .Ar archive .
 257 Invoking
 258 .Nm
 259 with the
 260 .Fl s
 261 option alone is equivalent to invoking
 262 .Nm ranlib .
 263 .It Fl t
 264 List the files specified by arguments
 265 .Ar files ...
 266 in the order in which they appear in the archive, one per line.
 267 If no files are specified, all files in the archive are listed.
 268 .It Fl T
 269 Use only the first fifteen characters of the archive member name or
 270 command line file name argument when naming archive members.
 271 .It Fl u
 272 Conditionally update the archive or extract members.
 273 When used with the
 274 .Fl r
 275 option, files named by arguments
 276 .Ar files ...
 277 will be replaced in the archive if they are newer than their
 278 archived versions.
 279 When used with the
 280 .Fl x
 281 option, the members specified by arguments
 282 .Ar files ...
 283 will be extracted only if they are newer than the corresponding
 284 files in the file system.
 285 .It Fl v
 286 Provide verbose output.
 287 When used with the
 288 .Fl d ,
 289 .Fl m ,
 290 .Fl q
 291 or
 292 .Fl x
 293 options,
 294 .Nm
 295 gives a file-by-file description of the archive modification being
 296 performed, which consists of three white-space seperated fields:
 297 the option letter, a dash
 298 .Dq "-" ,
 299 and the file name.
 300 When used with the
 301 .Fl r
 302 option,
 303 .Nm
 304 displays the description as above, but the initial letter is an
 305 .Dq a
 306 if the file is added to the archive, or an
 307 .Dq r
 308 if the file replaces a file already in the archive.
 309 When used with the
 310 .Fl p
 311 option, the name of the file enclosed in
 312 .Dq <
 313 and
 314 .Dq >
 315 characters is written to standard output preceded by a single newline
 316 character and followed by two newline characters.
 317 The contents of the named file follow the file name.
 318 When used with the
 319 .Fl t
 320 option,
 321 .Nm
 322 displays eight whitespace separated fields:
 323 the file permissions as displayed by
 324 .Xr strmode 3 ,
 325 decimal user and group IDs separated by a slash (
 326 .Dq / Ns ) ,
 327 the file size in bytes, the file modification time in
 328 .Xr strftime 3
 329 format
 330 .Dq "%b %e %H:%M %Y" ,
 331 and the name of the file.
 332 .It Fl x
 333 Extract archive members specified by arguments
 334 .Ar files ...
 335 into the current directory.
 336 If no members have been specified, extract all members of the archive.
 337 If the file corresponding to an extracted member does not exist it
 338 will be created.
 339 If the file corresponding to an extracted member does exist, its owner
 340 and group will not be changed while its contents will be overwritten
 341 and its permissions will set to that entered in the archive.
 342 The file's access and modification time would be that of the time
 343 of extraction unless the
 344 .Fl o
 345 option was specified.
 346 .It Fl z
 347 Compress the resulting archive with
 348 .Xr gzip 1 .
 349 .El
 350 .Sh EXAMPLES
 351 To create a new archive
 352 .Pa ex.a
 353 containing three files
 354 .Pa ex1.o ,
 355 .Pa ex2.o
 356 and
 357 .Pa ex3.o ,
 358 use:
 359 .Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
 360 .Pp
 361 To add an archive symbol table to an existing archive
 362 .Pa ex.a ,
 363 use:
 364 .Dl "ar -s ex.a"
 365 .Pp
 366 To delete file
 367 .Pa ex1.o
 368 from archive
 369 .Pa ex.a ,
 370 use:
 371 .D1 "ar -d ex.a ex1.o"
 372 .Pp
 373 To verbosely list the contents of archive
 374 .Pa ex.a ,
 375 use:
 376 .D1 "ar -tv ex.a"
 377 .Sh DIAGNOSTICS
 378 .Ex -std
 379 .Sh SEE ALSO
 380 .Xr ld 1 ,
 381 .Xr archive 3 ,
 382 .Xr elf 3 ,
 383 .Xr strftime 3 ,
 384 .Xr strmode 3 ,
 385 .Xr ar 5
 386 .\" .Sh COMPATIBILITY
 387 .\" .Nm
 388 .\" is expected to be compatible with GNU and SVR4
 389 .\" .Nm .
 390 .\" .Sh STANDARDS
 391 .\" Do the POSIX/SuSv3 standards have anything to say about AR(1)?
 392 .Sh HISTORY
 393 An
 394 .Nm
 395 command first appeared in AT&T UNIX Version 1.
 396 In
 397 .Fx 8.0 ,
 398 .An "Kai Wang" Aq kaiw@FreeBSD.org
 399 reimplemented
 400 .Nm
 401 and
 402 .Nm ranlib
 403 using the
 404 .Lb libarchive
 405 and the
 406 .Lb libelf .