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$
  37 .\"
  38 .Dd June 29, 1993
  39 .Dt AR 1
  40 .Os
  41 .Sh NAME
  42 .Nm ar
  43 .Nd create and maintain library archives
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Fl d
  47 .Op Fl \&Tv
  48 .Ar archive Ar
  49 .Nm
  50 .Fl m
  51 .Op Fl \&Tv
  52 .Ar archive Ar
  53 .Nm
  54 .Fl m
  55 .Op Fl abiTv
  56 .Ar position archive Ar
  57 .Nm
  58 .Fl p
  59 .Op Fl \&Tv
  60 .Ar archive Op Ar
  61 .Nm
  62 .Fl q
  63 .Op Fl cTv
  64 .Ar archive Ar
  65 .Nm
  66 .Fl r
  67 .Op Fl cuTv
  68 .Ar archive Ar
  69 .Nm
  70 .Fl r
  71 .Op Fl abciuTv
  72 .Ar position archive Ar
  73 .Nm
  74 .Fl t
  75 .Op Fl \&Tv
  76 .Ar archive Op Ar
  77 .Nm
  78 .Fl x
  79 .Op Fl ouTv
  80 .Ar archive Op Ar
  81 .Sh DESCRIPTION
  82 The
  83 .Nm
  84 utility creates and maintains groups of files combined into an archive.
  85 Once an archive has been created, new files can be added and existing
  86 files can be extracted, deleted, or replaced.
  87 .Pp
  88 Files are named in the archive by a single component, i.e., if a file
  89 referenced by a path containing a slash (``/'') is archived it will be
  90 named by the last component of that path.
  91 When matching paths listed on the command line against file names stored
  92 in the archive, only the last component of the path will be compared.
  93 .Pp
  94 All informational and error messages use the path listed on the command
  95 line, if any was specified; otherwise the name in the archive is used.
  96 If multiple files in the archive have the same name, and paths are listed
  97 on the command line to ``select'' archive files for an operation, only the
  98 .Em first
  99 file with a matching name will be selected.
 100 .Pp
 101 The normal use of
 102 .Nm
 103 is for the creation and maintenance of libraries suitable for use with
 104 the loader (see
 105 .Xr ld 1 )
 106 although it is not restricted to this purpose.
 107 The options are as follows:
 108 .Bl -tag -width indent
 109 .It Fl a
 110 A positioning modifier used with the options
 111 .Fl r
 112 and
 113 .Fl m .
 114 The files are entered or moved
 115 .Em after
 116 the archive member
 117 .Ar position ,
 118 which must be specified.
 119 .It Fl b
 120 A positioning modifier used with the options
 121 .Fl r
 122 and
 123 .Fl m .
 124 The files are entered or moved
 125 .Em before
 126 the archive member
 127 .Ar position ,
 128 which must be specified.
 129 .It Fl c
 130 Whenever an archive is created, an informational message to that effect
 131 is written to standard error.
 132 If the
 133 .Fl c
 134 option is specified,
 135 .Nm
 136 creates the archive silently.
 137 .It Fl d
 138 Delete the specified archive files.
 139 .It Fl i
 140 Identical to the
 141 .Fl b
 142 option.
 143 .It Fl m
 144 Move the specified archive files within the archive.
 145 If one of the options
 146 .Fl a ,
 147 .Fl b
 148 or
 149 .Fl i
 150 is specified, the files are moved
 151 before or after the
 152 .Ar position
 153 file in the archive.
 154 If none of those options are specified, the files are moved
 155 to the end of the archive.
 156 .It Fl o
 157 Set the access and modification times of extracted files to the
 158 modification time of the file when it was entered into the archive.
 159 This will fail if the user is not the owner of the extracted file
 160 or the super-user.
 161 .It Fl p
 162 Write the contents of the specified archive files to the standard output.
 163 If no files are specified, the contents of all the files in the archive
 164 are written in the order they appear in the archive.
 165 .It Fl q
 166 (Quickly) append the specified files to the archive.
 167 If the archive does not exist a new archive file is created.
 168 Much faster than the
 169 .Fl r
 170 option, when creating a large archive
 171 piece-by-piece, as no checking is done to see if the files already
 172 exist in the archive.
 173 .It Fl r
 174 Replace or add the specified files to the archive.
 175 If the archive does not exist a new archive file is created.
 176 Files that replace existing files do not change the order of the files
 177 within the archive.
 178 New files are appended to the archive unless one of the options
 179 .Fl a ,
 180 .Fl b
 181 or
 182 .Fl i
 183 is specified.
 184 .It Fl T
 185 Select and/or name archive members using only the first fifteen characters
 186 of the archive member or command line file name.
 187 The historic archive format had sixteen bytes for the name, but some
 188 historic archiver and loader implementations were unable to handle names
 189 that used the entire space.
 190 This means that file names that are not unique in their first fifteen
 191 characters can subsequently be confused.
 192 A warning message is printed to the standard error output if any file
 193 names are truncated.
 194 (See
 195 .Xr ar 5
 196 for more information.)
 197 .It Fl t
 198 List the specified files in the order in which they appear in the archive,
 199 each on a separate line.
 200 If no files are specified, all files in the archive are listed.
 201 .It Fl u
 202 Update files.
 203 When used with the
 204 .Fl r
 205 option, files in the archive will be replaced
 206 only if the disk file has a newer modification time than the file in
 207 the archive.
 208 When used with the
 209 .Fl x
 210 option, files in the archive will be extracted
 211 only if the archive file has a newer modification time than the file
 212 on disk.
 213 .It Fl v
 214 Provide verbose output.
 215 When used with the
 216 .Fl d ,
 217 .Fl m ,
 218 .Fl q
 219 or
 220 .Fl x
 221 options,
 222 .Nm
 223 gives a file-by-file description of the archive modification.
 224 This description consists of three, white-space separated fields: the
 225 option letter, a dash (``-'') and the file name.
 226 When used with the
 227 .Fl r
 228 option,
 229 .Nm
 230 displays the description as above, but the initial letter is an ``a'' if
 231 the file is added to the archive and an ``r'' if the file replaces a file
 232 already in the archive.
 233 .Pp
 234 When used with the
 235 .Fl p
 236 option,
 237 the name of each printed file,
 238 enclosed in less-than (``<'') and greater-than (``>'') characters,
 239 is written to the standard output before
 240 the contents of the file;
 241 it is preceded by a single newline character, and
 242 followed by two newline characters.
 243 .Pp
 244 When used with the
 245 .Fl t
 246 option,
 247 .Nm
 248 displays an ``ls -l'' style listing of information about the members of
 249 the archive.
 250 This listing consists of eight, white-space separated fields:
 251 the file permissions (see
 252 .Xr strmode 3 ) ,
 253 the decimal user and group ID's, separated by a single slash (``/''),
 254 the file size (in bytes), the file modification time (in the
 255 .Xr date 1
 256 format ``%b %e %H:%M %Y''), and the name of the file.
 257 .It Fl x
 258 Extract the specified archive members into the files named by the command
 259 line arguments.
 260 If no members are specified, all the members of the archive are extracted into
 261 the current directory.
 262 .Pp
 263 If the file does not exist, it is created; if it does exist, the owner
 264 and group will be unchanged.
 265 The file access and modification times are the time of the extraction
 266 (but see the
 267 .Fl o
 268 option).
 269 The file permissions will be set to those of the file when it was entered
 270 into the archive; this will fail if the user is not the owner of the
 271 extracted file or the super-user.
 272 .El
 273 .Pp
 274 The
 275 .Nm
 276 utility exits 0 on success, and >0 if an error occurs.
 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