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