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