usr.bin/ar/ar.1aout

   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.1aout,v 1.6.2.4 2001/08/16 13:16:41 ru Exp $
  37 .\" $DragonFly: src/usr.bin/ar/Attic/ar.1aout,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 The options are as follows:
 109 .Bl -tag -width indent
 110 .It Fl a
 111 A positioning modifier used with the options
 112 .Fl r
 113 and
 114 .Fl m .
 115 The files are entered or moved
 116 .Em after
 117 the archive member
 118 .Ar position ,
 119 which must be specified.
 120 .It Fl b
 121 A positioning modifier used with the options
 122 .Fl r
 123 and
 124 .Fl m .
 125 The files are entered or moved
 126 .Em before
 127 the archive member
 128 .Ar position ,
 129 which must be specified.
 130 .It Fl c
 131 Whenever an archive is created, an informational message to that effect
 132 is written to standard error.
 133 If the
 134 .Fl c
 135 option is specified,
 136 .Nm
 137 creates the archive silently.
 138 .It Fl d
 139 Delete the specified archive files.
 140 .It Fl i
 141 Identical to the
 142 .Fl b
 143 option.
 144 .It Fl m
 145 Move the specified archive files within the archive.
 146 If one of the options
 147 .Fl a ,
 148 .Fl b
 149 or
 150 .Fl i
 151 is specified, the files are moved
 152 before or after the
 153 .Ar position
 154 file in the archive.
 155 If none of those options are specified, the files are moved
 156 to the end of the archive.
 157 .It Fl o
 158 Set the access and modification times of extracted files to the
 159 modification time of the file when it was entered into the archive.
 160 This will fail if the user is not the owner of the extracted file
 161 or the super-user.
 162 .It Fl p
 163 Write the contents of the specified archive files to the standard output.
 164 If no files are specified, the contents of all the files in the archive
 165 are written in the order they appear in the archive.
 166 .It Fl q
 167 (Quickly) append the specified files to the archive.
 168 If the archive does not exist a new archive file is created.
 169 Much faster than the
 170 .Fl r
 171 option, when creating a large archive
 172 piece-by-piece, as no checking is done to see if the files already
 173 exist in the archive.
 174 .It Fl r
 175 Replace or add the specified files to the archive.
 176 If the archive does not exist a new archive file is created.
 177 Files that replace existing files do not change the order of the files
 178 within the archive.
 179 New files are appended to the archive unless one of the options
 180 .Fl a ,
 181 .Fl b
 182 or
 183 .Fl i
 184 is specified.
 185 .It Fl T
 186 Select and/or name archive members using only the first fifteen characters
 187 of the archive member or command line file name.
 188 The historic archive format had sixteen bytes for the name, but some
 189 historic archiver and loader implementations were unable to handle names
 190 that used the entire space.
 191 This means that file names that are not unique in their first fifteen
 192 characters can subsequently be confused.
 193 A warning message is printed to the standard error output if any file
 194 names are truncated.
 195 (See
 196 .Xr ar 5
 197 for more information.)
 198 .It Fl t
 199 List the specified files in the order in which they appear in the archive,
 200 each on a separate line.
 201 If no files are specified, all files in the archive are listed.
 202 .It Fl u
 203 Update files.
 204 When used with the
 205 .Fl r
 206 option, files in the archive will be replaced
 207 only if the disk file has a newer modification time than the file in
 208 the archive.
 209 When used with the
 210 .Fl x
 211 option, files in the archive will be extracted
 212 only if the archive file has a newer modification time than the file
 213 on disk.
 214 .It Fl v
 215 Provide verbose output.
 216 When used with the
 217 .Fl d ,
 218 .Fl m ,
 219 .Fl q
 220 or
 221 .Fl x
 222 options,
 223 .Nm
 224 gives a file-by-file description of the archive modification.
 225 This description consists of three, white-space separated fields: the
 226 option letter, a dash (``-'') and the file name.
 227 When used with the
 228 .Fl r
 229 option,
 230 .Nm
 231 displays the description as above, but the initial letter is an ``a'' if
 232 the file is added to the archive and an ``r'' if the file replaces a file
 233 already in the archive.
 234 .Pp
 235 When used with the
 236 .Fl p
 237 option,
 238 the name of each printed file,
 239 enclosed in less-than (``<'') and greater-than (``>'') characters,
 240 is written to the standard output before
 241 the contents of the file;
 242 it is preceded by a single newline character, and
 243 followed by two newline characters.
 244 .Pp
 245 When used with the
 246 .Fl t
 247 option,
 248 .Nm
 249 displays an ``ls -l'' style listing of information about the members of
 250 the archive.
 251 This listing consists of eight, white-space separated fields:
 252 the file permissions (see
 253 .Xr strmode 3 ) ,
 254 the decimal user and group ID's, separated by a single slash (``/''),
 255 the file size (in bytes), the file modification time (in the
 256 .Xr date 1
 257 format ``%b %e %H:%M %Y''), and the name of the file.
 258 .It Fl x
 259 Extract the specified archive members into the files named by the command
 260 line arguments.
 261 If no members are specified, all the members of the archive are extracted into
 262 the current directory.
 263 .Pp
 264 If the file does not exist, it is created; if it does exist, the owner
 265 and group will be unchanged.
 266 The file access and modification times are the time of the extraction
 267 (but see the
 268 .Fl o
 269 option).
 270 The file permissions will be set to those of the file when it was entered
 271 into the archive; this will fail if the user is not the owner of the
 272 extracted file or the super-user.
 273 .El
 274 .Sh DIAGNOSTICS
 275 .Ex -std
 276 .Sh ENVIRONMENT
 277 .Bl -tag -width indent -compact
 278 .It Ev TMPDIR
 279 The pathname of the directory to use when creating temporary files.
 280 .El
 281 .Sh FILES
 282 .Bl -tag -width indent -compact
 283 .It Pa /tmp
 284 default temporary file directory
 285 .It Pa ar.XXXXXX
 286 temporary file names
 287 .El
 288 .Sh COMPATIBILITY
 289 By default,
 290 .Nm
 291 writes archives that may be incompatible with historic archives, as
 292 the format used for storing archive members with names longer than
 293 fifteen characters has changed.
 294 This implementation of
 295 .Nm
 296 is backward compatible with previous versions of
 297 .Nm
 298 in that it can read and write (using the
 299 .Fl T
 300 option) historic archives.
 301 The
 302 .Fl T
 303 option is provided for compatibility only, and will be deleted
 304 in a future release.
 305 See
 306 .Xr ar 5
 307 for more information.
 308 .Sh STANDARDS
 309 The
 310 .Nm
 311 utility is expected to offer a superset of the
 312 .St -p1003.2
 313 functionality.
 314 .Sh SEE ALSO
 315 .Xr ld 1 ,
 316 .Xr ranlib 1 ,
 317 .Xr strmode 3 ,
 318 .Xr ar 5