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 May 17, 2010
  27 .Dt AR 1
  28 .Os
  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 D
  66 .Op Fl i Ar position-before
  67 .Op Fl j
  68 .Op Fl s
  69 .Op Fl u
  70 .Op Fl v
  71 .Op Fl z
  72 .Ar archive
  73 .Ar files ...
  74 .Nm
  75 .Fl s
  76 .Op Fl j
  77 .Op Fl z
  78 .Ar archive
  79 .Nm
  80 .Fl t
  81 .Op Fl T
  82 .Op Fl v
  83 .Ar archive
  84 .Op Ar files ...
  85 .Nm
  86 .Fl x
  87 .Op Fl C
  88 .Op Fl T
  89 .Op Fl o
  90 .Op Fl u
  91 .Op Fl v
  92 .Ar archive
  93 .Op Ar files ...
  94 .Nm ranlib
  95 .Ar archive ...
  96 .Sh DESCRIPTION
  97 The
  98 .Nm
  99 utility creates and maintains groups of files combined into an
 100 archive.
 101 Once an archive has been created, new files can be added to it, and
 102 existing files can be extracted, deleted or replaced.
 103 .Pp
 104 Files are named in the archive by their last file name component,
 105 so if a file referenced by a path containing a
 106 .Dq /
 107 is archived, it will be named by the last component of the path.
 108 Similarly when matching paths listed on the command line against
 109 file names stored in the archive, only the last component of the
 110 path will be compared.
 111 .Pp
 112 The normal use of
 113 .Nm
 114 is for the creation and maintenance of libraries suitable for use
 115 with the link editor
 116 .Xr ld 1 ,
 117 although it is not restricted to this purpose.
 118 The
 119 .Nm
 120 utility can create and manage an archive symbol table (see
 121 .Xr ar 5 )
 122 used to speed up link editing operations.
 123 If a symbol table is present in an archive, it will be
 124 kept up-to-date by subsequent operations on the archive (excepting
 125 the quick update specified by the
 126 .Fl q
 127 option).
 128 .Pp
 129 The
 130 .Nm ranlib
 131 utility is used to add an archive symbol table
 132 to an existing archive.
 133 .Sh OPTIONS
 134 The
 135 .Nm
 136 utility supports the following options:
 137 .Bl -tag -width indent
 138 .It Fl a Ar member-after
 139 When used with option
 140 .Fl m
 141 this option specifies that the archive members specified by
 142 arguments
 143 .Ar files ...
 144 are moved to after the archive member named by argument
 145 .Ar member-after .
 146 When used with option
 147 .Fl r
 148 this option specifies that the files specified by arguments
 149 .Ar files ...
 150 are added after the archive member named by argument
 151 .Ar member-after .
 152 .It Fl b Ar member-before
 153 When used with option
 154 .Fl m
 155 this option specifies that the archive members specified by
 156 arguments
 157 .Ar files ...
 158 are moved to before the archive member named by argument
 159 .Ar member-before .
 160 When used with option
 161 .Fl r
 162 this option specifies that the files specified by arguments
 163 .Ar files ...
 164 are added before the archive member named by argument
 165 .Ar member-before .
 166 .It Fl c
 167 Suppress the informational message printed when a new archive is
 168 created using the
 169 .Fl r
 170 and
 171 .Fl q
 172 options.
 173 .It Fl C
 174 Prevent extracted files from replacing like-named files
 175 in the file system.
 176 .It Fl d
 177 Delete the members named by arguments
 178 .Ar files ...
 179 from the archive specified by argument
 180 .Ar archive .
 181 The archive's symbol table, if present, is updated to reflect
 182 the new contents of the archive.
 183 .It Fl D
 184 When used in combination with the
 185 .Fl r
 186 or
 187 .Fl q
 188 option, insert 0's instead of the real mtime, uid and gid values
 189 and 0644 instead of file mode from the members named by arguments
 190 .Ar files ... .
 191 This ensures that checksums on the resulting archives are reproducible
 192 when member contents are identical.
 193 .It Fl f
 194 Synonymous with option
 195 .Fl T .
 196 .It Fl i Ar member-before
 197 Synonymous with option
 198 .Fl b .
 199 .It Fl j
 200 This option is accepted but ignored.
 201 .It Fl m
 202 Move archive members specified by arguments
 203 .Ar files ...
 204 within the archive.
 205 If a position has been specified by one of the
 206 .Fl a ,
 207 .Fl b
 208 or
 209 .Fl i
 210 options, the members are moved to before or after the specified
 211 position.
 212 If no position has been specified, the specified members are moved
 213 to the end of the archive.
 214 If the archive has a symbol table, it is updated to reflect the
 215 new contents of the archive.
 216 .It Fl o
 217 Preserve the original modification times of members when extracting
 218 them.
 219 .It Fl p
 220 Write the contents of the specified archive members named by
 221 arguments
 222 .Ar files ...
 223 to standard output.
 224 If no members were specified, the contents of all the files in the
 225 archive are written in the order they appear in the archive.
 226 .It Fl q
 227 Append the files specified by arguments
 228 .Ar files ...
 229 to the archive specified by argument
 230 .Ar archive
 231 without checking if the files already exist in the archive and
 232 without updating the archive's symbol table.
 233 If the archive file
 234 .Ar archive
 235 does not already exist, a new archive is created.
 236 However, to be compatible with GNU
 237 .Nm ,
 238 option
 239 .Fl q
 240 will update the archive's symbol table.
 241 .It Fl r
 242 Replace (add) the files specified by arguments
 243 .Ar files ...
 244 in the archive specified by argument
 245 .Ar archive ,
 246 creating the archive if necessary.
 247 Files that replace existing files do not change the order of files
 248 within the archive.
 249 If a file named in arguments
 250 .Ar files ...
 251 does not exist, existing members in the archive that match that
 252 name are not changed.
 253 New files are added to the end of the archive unless one of the
 254 positioning options
 255 .Fl a ,
 256 .Fl b
 257 or
 258 .Fl i
 259 is specified.
 260 The archive symbol table, if it exists, is updated to reflect the
 261 new state of the archive.
 262 .It Fl s
 263 Add an archive symbol table (see
 264 .Xr ar 5 )
 265 to the archive specified by argument
 266 .Ar archive .
 267 Invoking
 268 .Nm
 269 with the
 270 .Fl s
 271 option alone is equivalent to invoking
 272 .Nm ranlib .
 273 .It Fl t
 274 List the files specified by arguments
 275 .Ar files ...
 276 in the order in which they appear in the archive, one per line.
 277 If no files are specified, all files in the archive are listed.
 278 .It Fl T
 279 Use only the first fifteen characters of the archive member name or
 280 command line file name argument when naming archive members.
 281 .It Fl u
 282 Conditionally update the archive or extract members.
 283 When used with the
 284 .Fl r
 285 option, files named by arguments
 286 .Ar files ...
 287 will be replaced in the archive if they are newer than their
 288 archived versions.
 289 When used with the
 290 .Fl x
 291 option, the members specified by arguments
 292 .Ar files ...
 293 will be extracted only if they are newer than the corresponding
 294 files in the file system.
 295 .It Fl v
 296 Provide verbose output.
 297 When used with the
 298 .Fl d ,
 299 .Fl m ,
 300 .Fl q
 301 or
 302 .Fl x
 303 options,
 304 .Nm
 305 gives a file-by-file description of the archive modification being
 306 performed, which consists of three white-space separated fields:
 307 the option letter, a dash
 308 .Dq "-" ,
 309 and the file name.
 310 When used with the
 311 .Fl r
 312 option,
 313 .Nm
 314 displays the description as above, but the initial letter is an
 315 .Dq a
 316 if the file is added to the archive, or an
 317 .Dq r
 318 if the file replaces a file already in the archive.
 319 When used with the
 320 .Fl p
 321 option, the name of the file enclosed in
 322 .Dq <
 323 and
 324 .Dq >
 325 characters is written to standard output preceded by a single newline
 326 character and followed by two newline characters.
 327 The contents of the named file follow the file name.
 328 When used with the
 329 .Fl t
 330 option,
 331 .Nm
 332 displays eight whitespace separated fields:
 333 the file permissions as displayed by
 334 .Xr strmode 3 ,
 335 decimal user and group IDs separated by a slash (
 336 .Dq / Ns ) ,
 337 the file size in bytes, the file modification time in
 338 .Xr strftime 3
 339 format
 340 .Dq "%b %e %H:%M %Y" ,
 341 and the name of the file.
 342 .It Fl x
 343 Extract archive members specified by arguments
 344 .Ar files ...
 345 into the current directory.
 346 If no members have been specified, extract all members of the archive.
 347 If the file corresponding to an extracted member does not exist it
 348 will be created.
 349 If the file corresponding to an extracted member does exist, its owner
 350 and group will not be changed while its contents will be overwritten
 351 and its permissions will set to that entered in the archive.
 352 The file's access and modification time would be that of the time
 353 of extraction unless the
 354 .Fl o
 355 option was specified.
 356 .It Fl z
 357 This option is accepted but ignored.
 358 .El
 359 .Sh EXAMPLES
 360 To create a new archive
 361 .Pa ex.a
 362 containing three files
 363 .Pa ex1.o ,
 364 .Pa ex2.o
 365 and
 366 .Pa ex3.o ,
 367 use:
 368 .Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
 369 .Pp
 370 To add an archive symbol table to an existing archive
 371 .Pa ex.a ,
 372 use:
 373 .Dl "ar -s ex.a"
 374 .Pp
 375 To delete file
 376 .Pa ex1.o
 377 from archive
 378 .Pa ex.a ,
 379 use:
 380 .D1 "ar -d ex.a ex1.o"
 381 .Pp
 382 To verbosely list the contents of archive
 383 .Pa ex.a ,
 384 use:
 385 .D1 "ar -tv ex.a"
 386 .Sh DIAGNOSTICS
 387 .Ex -std
 388 .Sh SEE ALSO
 389 .Xr ld 1 ,
 390 .Xr archive 3 ,
 391 .Xr elf 3 ,
 392 .Xr strftime 3 ,
 393 .Xr strmode 3 ,
 394 .Xr ar 5
 395 .\" .Sh COMPATIBILITY
 396 .\" .Nm
 397 .\" is expected to be compatible with GNU and SVR4
 398 .\" .Nm .
 399 .\" .Sh STANDARDS
 400 .\" Do the POSIX/SuSv3 standards have anything to say about AR(1)?
 401 .Sh HISTORY
 402 An
 403 .Nm
 404 command first appeared in AT&T UNIX Version 1.
 405 In
 406 .Fx 8.0 ,
 407 .An "Kai Wang" Aq kaiw@FreeBSD.org
 408 reimplemented
 409 .Nm
 410 and
 411 .Nm ranlib
 412 using the
 413 .Lb libarchive
 414 and the
 415 .Lb libelf .