cctools/ar/ar.1

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