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