1.\" Copyright (c) 2007 Joseph Koshy. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" This software is provided by Joseph Koshy ``as is'' and 13.\" any express or implied warranties, including, but not limited to, the 14.\" implied warranties of merchantability and fitness for a particular purpose 15.\" are disclaimed. in no event shall Joseph Koshy be liable 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd May 17, 2010 27.Dt AR 1 28.Os 29.Sh NAME 30.Nm ar , 31.Nm ranlib 32.Nd manage archives 33.Sh SYNOPSIS 34.Nm 35.Fl d 36.Op Fl T 37.Op Fl j 38.Op Fl v 39.Op Fl z 40.Ar archive 41.Ar files ... 42.Nm 43.Fl m 44.Op Fl T 45.Op Fl a Ar position-after 46.Op Fl b Ar position-before 47.Op Fl i Ar position-before 48.Op Fl j 49.Op Fl s 50.Op Fl z 51.Ar archive 52.Ar files ... 53.Nm 54.Fl p 55.Op Fl T 56.Op Fl v 57.Ar archive 58.Op Ar files ... 59.Nm 60.Fl r 61.Op Fl T 62.Op Fl a Ar position-after 63.Op Fl b Ar position-before 64.Op Fl c 65.Op Fl D 66.Op Fl i Ar position-before 67.Op Fl j 68.Op Fl s 69.Op Fl u 70.Op Fl v 71.Op Fl z 72.Ar archive 73.Ar files ... 74.Nm 75.Fl s 76.Op Fl j 77.Op Fl z 78.Ar archive 79.Nm 80.Fl t 81.Op Fl T 82.Op Fl v 83.Ar archive 84.Op Ar files ... 85.Nm 86.Fl x 87.Op Fl C 88.Op Fl T 89.Op Fl o 90.Op Fl u 91.Op Fl v 92.Ar archive 93.Op Ar files ... 94.Nm ranlib 95.Ar archive ... 96.Sh DESCRIPTION 97The 98.Nm 99utility creates and maintains groups of files combined into an 100archive. 101Once an archive has been created, new files can be added to it, and 102existing files can be extracted, deleted or replaced. 103.Pp 104Files are named in the archive by their last file name component, 105so if a file referenced by a path containing a 106.Dq / 107is archived, it will be named by the last component of the path. 108Similarly when matching paths listed on the command line against 109file names stored in the archive, only the last component of the 110path will be compared. 111.Pp 112The normal use of 113.Nm 114is for the creation and maintenance of libraries suitable for use 115with the link editor 116.Xr ld 1 , 117although it is not restricted to this purpose. 118The 119.Nm 120utility can create and manage an archive symbol table (see 121.Xr ar 5 ) 122used to speed up link editing operations. 123If a symbol table is present in an archive, it will be 124kept up-to-date by subsequent operations on the archive (excepting 125the quick update specified by the 126.Fl q 127option). 128.Pp 129The 130.Nm ranlib 131utility is used to add an archive symbol table 132to an existing archive. 133.Sh OPTIONS 134The 135.Nm 136utility supports the following options: 137.Bl -tag -width indent 138.It Fl a Ar member-after 139When used with option 140.Fl m 141this option specifies that the archive members specified by 142arguments 143.Ar files ... 144are moved to after the archive member named by argument 145.Ar member-after . 146When used with option 147.Fl r 148this option specifies that the files specified by arguments 149.Ar files ... 150are added after the archive member named by argument 151.Ar member-after . 152.It Fl b Ar member-before 153When used with option 154.Fl m 155this option specifies that the archive members specified by 156arguments 157.Ar files ... 158are moved to before the archive member named by argument 159.Ar member-before . 160When used with option 161.Fl r 162this option specifies that the files specified by arguments 163.Ar files ... 164are added before the archive member named by argument 165.Ar member-before . 166.It Fl c 167Suppress the informational message printed when a new archive is 168created using the 169.Fl r 170and 171.Fl q 172options. 173.It Fl C 174Prevent extracted files from replacing like-named files 175in the file system. 176.It Fl d 177Delete the members named by arguments 178.Ar files ... 179from the archive specified by argument 180.Ar archive . 181The archive's symbol table, if present, is updated to reflect 182the new contents of the archive. 183.It Fl D 184When used in combination with the 185.Fl r 186or 187.Fl q 188option, insert 0's instead of the real mtime, uid and gid values 189and 0644 instead of file mode from the members named by arguments 190.Ar files ... . 191This ensures that checksums on the resulting archives are reproducible 192when member contents are identical. 193.It Fl f 194Synonymous with option 195.Fl T . 196.It Fl i Ar member-before 197Synonymous with option 198.Fl b . 199.It Fl j 200This option is accepted but ignored. 201.It Fl m 202Move archive members specified by arguments 203.Ar files ... 204within the archive. 205If a position has been specified by one of the 206.Fl a , 207.Fl b 208or 209.Fl i 210options, the members are moved to before or after the specified 211position. 212If no position has been specified, the specified members are moved 213to the end of the archive. 214If the archive has a symbol table, it is updated to reflect the 215new contents of the archive. 216.It Fl o 217Preserve the original modification times of members when extracting 218them. 219.It Fl p 220Write the contents of the specified archive members named by 221arguments 222.Ar files ... 223to standard output. 224If no members were specified, the contents of all the files in the 225archive are written in the order they appear in the archive. 226.It Fl q 227Append the files specified by arguments 228.Ar files ... 229to the archive specified by argument 230.Ar archive 231without checking if the files already exist in the archive and 232without updating the archive's symbol table. 233If the archive file 234.Ar archive 235does not already exist, a new archive is created. 236However, to be compatible with GNU 237.Nm , 238option 239.Fl q 240will update the archive's symbol table. 241.It Fl r 242Replace (add) the files specified by arguments 243.Ar files ... 244in the archive specified by argument 245.Ar archive , 246creating the archive if necessary. 247Files that replace existing files do not change the order of files 248within the archive. 249If a file named in arguments 250.Ar files ... 251does not exist, existing members in the archive that match that 252name are not changed. 253New files are added to the end of the archive unless one of the 254positioning options 255.Fl a , 256.Fl b 257or 258.Fl i 259is specified. 260The archive symbol table, if it exists, is updated to reflect the 261new state of the archive. 262.It Fl s 263Add an archive symbol table (see 264.Xr ar 5 ) 265to the archive specified by argument 266.Ar archive . 267Invoking 268.Nm 269with the 270.Fl s 271option alone is equivalent to invoking 272.Nm ranlib . 273.It Fl t 274List the files specified by arguments 275.Ar files ... 276in the order in which they appear in the archive, one per line. 277If no files are specified, all files in the archive are listed. 278.It Fl T 279Use only the first fifteen characters of the archive member name or 280command line file name argument when naming archive members. 281.It Fl u 282Conditionally update the archive or extract members. 283When used with the 284.Fl r 285option, files named by arguments 286.Ar files ... 287will be replaced in the archive if they are newer than their 288archived versions. 289When used with the 290.Fl x 291option, the members specified by arguments 292.Ar files ... 293will be extracted only if they are newer than the corresponding 294files in the file system. 295.It Fl v 296Provide verbose output. 297When used with the 298.Fl d , 299.Fl m , 300.Fl q 301or 302.Fl x 303options, 304.Nm 305gives a file-by-file description of the archive modification being 306performed, which consists of three white-space separated fields: 307the option letter, a dash 308.Dq "-" , 309and the file name. 310When used with the 311.Fl r 312option, 313.Nm 314displays the description as above, but the initial letter is an 315.Dq a 316if the file is added to the archive, or an 317.Dq r 318if the file replaces a file already in the archive. 319When used with the 320.Fl p 321option, the name of the file enclosed in 322.Dq < 323and 324.Dq > 325characters is written to standard output preceded by a single newline 326character and followed by two newline characters. 327The contents of the named file follow the file name. 328When used with the 329.Fl t 330option, 331.Nm 332displays eight whitespace separated fields: 333the file permissions as displayed by 334.Xr strmode 3 , 335decimal user and group IDs separated by a slash ( 336.Dq / Ns ) , 337the file size in bytes, the file modification time in 338.Xr strftime 3 339format 340.Dq "%b %e %H:%M %Y" , 341and the name of the file. 342.It Fl x 343Extract archive members specified by arguments 344.Ar files ... 345into the current directory. 346If no members have been specified, extract all members of the archive. 347If the file corresponding to an extracted member does not exist it 348will be created. 349If the file corresponding to an extracted member does exist, its owner 350and group will not be changed while its contents will be overwritten 351and its permissions will set to that entered in the archive. 352The file's access and modification time would be that of the time 353of extraction unless the 354.Fl o 355option was specified. 356.It Fl z 357This option is accepted but ignored. 358.El 359.Sh EXAMPLES 360To create a new archive 361.Pa ex.a 362containing three files 363.Pa ex1.o , 364.Pa ex2.o 365and 366.Pa ex3.o , 367use: 368.Dl "ar -rc ex.a ex1.o ex2.o ex3.o" 369.Pp 370To add an archive symbol table to an existing archive 371.Pa ex.a , 372use: 373.Dl "ar -s ex.a" 374.Pp 375To delete file 376.Pa ex1.o 377from archive 378.Pa ex.a , 379use: 380.D1 "ar -d ex.a ex1.o" 381.Pp 382To verbosely list the contents of archive 383.Pa ex.a , 384use: 385.D1 "ar -tv ex.a" 386.Sh DIAGNOSTICS 387.Ex -std 388.Sh SEE ALSO 389.Xr ld 1 , 390.Xr archive 3 , 391.Xr elf 3 , 392.Xr strftime 3 , 393.Xr strmode 3 , 394.Xr ar 5 395.\" .Sh COMPATIBILITY 396.\" .Nm 397.\" is expected to be compatible with GNU and SVR4 398.\" .Nm . 399.\" .Sh STANDARDS 400.\" Do the POSIX/SuSv3 standards have anything to say about AR(1)? 401.Sh HISTORY 402An 403.Nm 404command first appeared in AT&T UNIX Version 1. 405In 406.Fx 8.0 , 407.An "Kai Wang" Aq kaiw@FreeBSD.org 408reimplemented 409.Nm 410and 411.Nm ranlib 412using the 413.Lb libarchive 414and the 415.Lb libelf . 416