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