usr.bin/ar/ar.1

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Hugh Smith at The University of Guelph.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)ar.1        8.1 (Berkeley) 6/29/93
  36 .\" $FreeBSD: src/usr.bin/ar/ar.1,v 1.6.2.8 2002/07/15 04:08:48 keramida Exp $
  37 .\" $DragonFly: src/usr.bin/ar/Attic/ar.1,v 1.2 2003/06/17 04:29:25 dillon Exp $
  38 .\"
  39 .Dd June 29, 1993
  40 .Dt AR 1
  41 .Os
  42 .Sh NAME
  43 .Nm ar
  44 .Nd create and maintain library archives
  45 .Sh SYNOPSIS
  46 .Nm
  47 .Fl d
  48 .Op Fl \&Tv
  49 .Ar archive Ar
  50 .Nm
  51 .Fl m
  52 .Op Fl \&Tv
  53 .Ar archive Ar
  54 .Nm
  55 .Fl m
  56 .Op Fl abiTv
  57 .Ar position archive Ar
  58 .Nm
  59 .Fl p
  60 .Op Fl \&Tv
  61 .Ar archive Op Ar
  62 .Nm
  63 .Fl q
  64 .Op Fl cTv
  65 .Ar archive Ar
  66 .Nm
  67 .Fl r
  68 .Op Fl cuTv
  69 .Ar archive Ar
  70 .Nm
  71 .Fl r
  72 .Op Fl abciuTv
  73 .Ar position archive Ar
  74 .Nm
  75 .Fl t
  76 .Op Fl \&Tv
  77 .Ar archive Op Ar
  78 .Nm
  79 .Fl x
  80 .Op Fl ouTv
  81 .Ar archive Op Ar
  82 .Sh DESCRIPTION
  83 The
  84 .Nm
  85 utility creates and maintains groups of files combined into an archive.
  86 Once an archive has been created, new files can be added and existing
  87 files can be extracted, deleted, or replaced.
  88 .Pp
  89 Files are named in the archive by a single component, i.e., if a file
  90 referenced by a path containing a slash (``/'') is archived it will be
  91 named by the last component of that path.
  92 When matching paths listed on the command line against file names stored
  93 in the archive, only the last component of the path will be compared.
  94 .Pp
  95 All informational and error messages use the path listed on the command
  96 line, if any was specified; otherwise the name in the archive is used.
  97 If multiple files in the archive have the same name, and paths are listed
  98 on the command line to ``select'' archive files for an operation, only the
  99 .Em first
 100 file with a matching name will be selected.
 101 .Pp
 102 The normal use of
 103 .Nm
 104 is for the creation and maintenance of libraries suitable for use with
 105 the loader (see
 106 .Xr ld 1 )
 107 although it is not restricted to this purpose.
 108 .Pp
 109 The options are as follows:
 110 .Bl -tag -width indent
 111 .It Fl a
 112 A positioning modifier used with the options
 113 .Fl r
 114 and
 115 .Fl m .
 116 The files are entered or moved
 117 .Em after
 118 the archive member
 119 .Ar position ,
 120 which must be specified.
 121 .It Fl b
 122 A positioning modifier used with the options
 123 .Fl r
 124 and
 125 .Fl m .
 126 The files are entered or moved
 127 .Em before
 128 the archive member
 129 .Ar position ,
 130 which must be specified.
 131 .It Fl c
 132 Whenever an archive is created, an informational message to that effect
 133 is written to standard error.
 134 If the
 135 .Fl c
 136 option is specified,
 137 .Nm
 138 creates the archive silently.
 139 .It Fl d
 140 Delete the specified archive files.
 141 .It Fl i
 142 Identical to the
 143 .Fl b
 144 option.
 145 .It Fl m
 146 Move the specified archive files within the archive.
 147 If one of the options
 148 .Fl a ,
 149 .Fl b
 150 or
 151 .Fl i
 152 is specified, the files are moved
 153 before or after the
 154 .Ar position
 155 file in the archive.
 156 If none of those options are specified, the files are moved
 157 to the end of the archive.
 158 .It Fl o
 159 Set the access and modification times of extracted files to the
 160 modification time of the file when it was entered into the archive.
 161 This will fail if the user is not the owner of the extracted file
 162 or the super-user.
 163 .It Fl p
 164 Write the contents of the specified archive files to the standard output.
 165 If no files are specified, the contents of all the files in the archive
 166 are written in the order they appear in the archive.
 167 .It Fl q
 168 (Quickly) append the specified files to the archive.
 169 If the archive does not exist a new archive file is created.
 170 Much faster than the
 171 .Fl r
 172 option, when creating a large archive
 173 piece-by-piece, as no checking is done to see if the files already
 174 exist in the archive.
 175 .It Fl r
 176 Replace or add the specified files to the archive.
 177 If the archive does not exist a new archive file is created.
 178 Files that replace existing files do not change the order of the files
 179 within the archive.
 180 New files are appended to the archive unless one of the options
 181 .Fl a ,
 182 .Fl b
 183 or
 184 .Fl i
 185 is specified.
 186 .It Fl T
 187 Select and/or name archive members using only the first fifteen characters
 188 of the archive member or command line file name.
 189 The historic archive format had sixteen bytes for the name, but some
 190 historic archiver and loader implementations were unable to handle names
 191 that used the entire space.
 192 This means that file names that are not unique in their first fifteen
 193 characters can subsequently be confused.
 194 A warning message is printed to the standard error output if any file
 195 names are truncated.
 196 (See
 197 .Xr ar 5
 198 for more information.)
 199 .It Fl t
 200 List the specified files in the order in which they appear in the archive,
 201 each on a separate line.
 202 If no files are specified, all files in the archive are listed.
 203 .It Fl u
 204 Update files.
 205 When used with the
 206 .Fl r
 207 option, files in the archive will be replaced
 208 only if the disk file has a newer modification time than the file in
 209 the archive.
 210 When used with the
 211 .Fl x
 212 option, files in the archive will be extracted
 213 only if the archive file has a newer modification time than the file
 214 on disk.
 215 .It Fl v
 216 Provide verbose output.
 217 When used with the
 218 .Fl d ,
 219 .Fl m ,
 220 .Fl q
 221 or
 222 .Fl x
 223 options,
 224 .Nm
 225 gives a file-by-file description of the archive modification.
 226 This description consists of three, white-space separated fields: the
 227 option letter, a dash (``-'') and the file name.
 228 When used with the
 229 .Fl r
 230 option,
 231 .Nm
 232 displays the description as above, but the initial letter is an ``a'' if
 233 the file is added to the archive and an ``r'' if the file replaces a file
 234 already in the archive.
 235 .Pp
 236 When used with the
 237 .Fl p
 238 option,
 239 the name of each printed file,
 240 enclosed in less-than (``<'') and greater-than (``>'') characters,
 241 is written to the standard output before
 242 the contents of the file;
 243 it is preceded by a single newline character, and
 244 followed by two newline characters.
 245 .Pp
 246 When used with the
 247 .Fl t
 248 option,
 249 .Nm
 250 displays an ``ls -l'' style listing of information about the members of
 251 the archive.
 252 This listing consists of eight, white-space separated fields:
 253 the file permissions (see
 254 .Xr strmode 3 ) ,
 255 the decimal user and group ID's, separated by a single slash (``/''),
 256 the file size (in bytes), the file modification time (in the
 257 .Xr date 1
 258 format ``%b %e %H:%M %Y''), and the name of the file.
 259 .It Fl x
 260 Extract the specified archive members into the files named by the command
 261 line arguments.
 262 If no members are specified, all the members of the archive are extracted into
 263 the current directory.
 264 .Pp
 265 If the file does not exist, it is created; if it does exist, the owner
 266 and group will be unchanged.
 267 The file access and modification times are the time of the extraction
 268 (but see the
 269 .Fl o
 270 option).
 271 The file permissions will be set to those of the file when it was entered
 272 into the archive; this will fail if the user is not the owner of the
 273 extracted file or the super-user.
 274 .El
 275 .Sh DIAGNOSTICS
 276 .Ex -std
 277 .Sh ENVIRONMENT
 278 .Bl -tag -width indent -compact
 279 .It Ev TMPDIR
 280 The pathname of the directory to use when creating temporary files.
 281 .El
 282 .Sh FILES
 283 .Bl -tag -width indent -compact
 284 .It Pa /tmp
 285 default temporary file directory
 286 .It Pa ar.XXXXXX
 287 temporary file names
 288 .El
 289 .Sh COMPATIBILITY
 290 By default,
 291 .Nm
 292 writes archives that may be incompatible with historic archives, as
 293 the format used for storing archive members with names longer than
 294 fifteen characters has changed.
 295 This implementation of
 296 .Nm
 297 is backward compatible with previous versions of
 298 .Nm
 299 in that it can read and write (using the
 300 .Fl T
 301 option) historic archives.
 302 The
 303 .Fl T
 304 option is provided for compatibility only, and will be deleted
 305 in a future release.
 306 See
 307 .Xr ar 5
 308 for more information.
 309 .Sh STANDARDS
 310 The
 311 .Nm
 312 utility is expected to offer a superset of the
 313 .St -p1003.2
 314 functionality.
 315 .Sh SEE ALSO
 316 .Xr ld 1 ,
 317 .Xr ranlib 1 ,
 318 .Xr strmode 3 ,
 319 .Xr ar 5