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