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 August 31, 2007 27.Os 28.Dt AR 1 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 i Ar position-before 66.Op Fl j 67.Op Fl s 68.Op Fl u 69.Op Fl v 70.Op Fl z 71.Ar archive 72.Ar files ... 73.Nm 74.Fl s 75.Op Fl j 76.Op Fl z 77.Ar archive 78.Nm 79.Fl t 80.Op Fl T 81.Op Fl v 82.Ar archive 83.Op Ar files ... 84.Nm 85.Fl x 86.Op Fl C 87.Op Fl T 88.Op Fl o 89.Op Fl u 90.Op Fl v 91.Ar archive 92.Op Ar files ... 93.Nm ranlib 94.Ar archive ... 95.Sh DESCRIPTION 96The 97.Nm 98utility creates and maintains groups of files combined into an 99archive. 100Once an archive has been created, new files can be added to it, and 101existing files can be extracted, deleted or replaced. 102.Pp 103Files are named in the archive by their last file name component, 104so if a file referenced by a path containing a 105.Dq / 106is archived, it will be named by the last component of the path. 107Similarly when matching paths listed on the command line against 108file names stored in the archive, only the last component of the 109path will be compared. 110.Pp 111The normal use of 112.Nm 113is for the creation and maintenance of libraries suitable for use 114with the link editor 115.Xr ld 1 , 116although it is not restricted to this purpose. 117The 118.Nm 119utility can create and manage an archive symbol table (see 120.Xr ar 5 ) 121used to speed up link editing operations. 122If a symbol table is present in an archive, it will be 123kept up-to-date by subsequent operations on the archive (excepting 124the quick update specified by the 125.Fl q 126option). 127.Pp 128The 129.Nm ranlib 130utility is used to add an archive symbol table 131to an existing archive. 132.Sh OPTIONS 133The 134.Nm 135utility supports the following options: 136.Bl -tag -width indent 137.It Fl a Ar member-after 138When used with option 139.Fl m 140this option specifies that the archive members specified by 141arguments 142.Ar files ... 143are moved to after the archive member named by argument 144.Ar member-after . 145When used with option 146.Fl r 147this option specifies that the files specified by arguments 148.Ar files ... 149are added after the archive member named by argument 150.Ar member-after . 151.It Fl b Ar member-before 152When used with option 153.Fl m 154this option specifies that the archive members specified by 155arguments 156.Ar files ... 157are moved to before the archive member named by argument 158.Ar member-before . 159When used with option 160.Fl r 161this option specifies that the files specified by arguments 162.Ar files ... 163are added before the archive member named by argument 164.Ar member-before . 165.It Fl c 166Suppress the informational message printed when a new archive is 167created using the 168.Fl r 169and 170.Fl q 171options. 172.It Fl C 173Prevent extracted files from replacing like-named files 174in the file system. 175.It Fl d 176Delete the members named by arguments 177.Ar files ... 178from the archive specified by argument 179.Ar archive . 180The archive's symbol table, if present, is updated to reflect 181the new contents of the archive. 182.It Fl f 183Synonymous with option 184.Fl T . 185.It Fl i Ar member-before 186Synonymous with option 187.Fl b . 188.It Fl j 189Compress the resulting archive with 190.Xr bzip2 1 . 191.It Fl m 192Move archive members specified by arguments 193.Ar files ... 194within the archive. 195If a position has been specified by one of the 196.Fl a , 197.Fl b 198or 199.Fl i 200options, the members are moved to before or after the specified 201position. 202If no position has been specified, the specified members are moved 203to the end of the archive. 204If the archive has a symbol table, it is updated to reflect the 205new contents of the archive. 206.It Fl o 207Preserve the original modification times of members when extracting 208them. 209.It Fl p 210Write the contents of the specified archive members named by 211arguments 212.Ar files ... 213to standard output. 214If no members were specified, the contents of all the files in the 215archive are written in the order they appear in the archive. 216.It Fl q 217Append the files specified by arguments 218.Ar files ... 219to the archive specified by argument 220.Ar archive 221without checking if the files already exist in the archive and 222without updating the archive's symbol table. 223If the archive file 224.Ar archive 225does not already exist, a new archive is created. 226However, to be compatible with GNU 227.Nm , 228option 229.Fl q 230will update the archive's symbol table. 231.It Fl r 232Replace (add) the files specified by arguments 233.Ar files ... 234in the archive specified by argument 235.Ar archive , 236creating the archive if necessary. 237Files that replace existing files do not change the order of files 238within the archive. 239If a file named in arguments 240.Ar files ... 241does not exist, existing members in the archive that match that 242name are not changed. 243New files are added to the end of the archive unless one of the 244positioning options 245.Fl a , 246.Fl b 247or 248.Fl i 249is specified. 250The archive symbol table, if it exists, is updated to reflect the 251new state of the archive. 252.It Fl s 253Add an archive symbol table (see 254.Xr ar 5 ) 255to the archive specified by argument 256.Ar archive . 257Invoking 258.Nm 259with the 260.Fl s 261option alone is equivalent to invoking 262.Nm ranlib . 263.It Fl t 264List the files specified by arguments 265.Ar files ... 266in the order in which they appear in the archive, one per line. 267If no files are specified, all files in the archive are listed. 268.It Fl T 269Use only the first fifteen characters of the archive member name or 270command line file name argument when naming archive members. 271.It Fl u 272Conditionally update the archive or extract members. 273When used with the 274.Fl r 275option, files named by arguments 276.Ar files ... 277will be replaced in the archive if they are newer than their 278archived versions. 279When used with the 280.Fl x 281option, the members specified by arguments 282.Ar files ... 283will be extracted only if they are newer than the corresponding 284files in the file system. 285.It Fl v 286Provide verbose output. 287When used with the 288.Fl d , 289.Fl m , 290.Fl q 291or 292.Fl x 293options, 294.Nm 295gives a file-by-file description of the archive modification being 296performed, which consists of three white-space seperated fields: 297the option letter, a dash 298.Dq "-" , 299and the file name. 300When used with the 301.Fl r 302option, 303.Nm 304displays the description as above, but the initial letter is an 305.Dq a 306if the file is added to the archive, or an 307.Dq r 308if the file replaces a file already in the archive. 309When used with the 310.Fl p 311option, the name of the file enclosed in 312.Dq < 313and 314.Dq > 315characters is written to standard output preceded by a single newline 316character and followed by two newline characters. 317The contents of the named file follow the file name. 318When used with the 319.Fl t 320option, 321.Nm 322displays eight whitespace separated fields: 323the file permissions as displayed by 324.Xr strmode 3 , 325decimal user and group IDs separated by a slash ( 326.Dq / Ns ) , 327the file size in bytes, the file modification time in 328.Xr strftime 3 329format 330.Dq "%b %e %H:%M %Y" , 331and the name of the file. 332.It Fl x 333Extract archive members specified by arguments 334.Ar files ... 335into the current directory. 336If no members have been specified, extract all members of the archive. 337If the file corresponding to an extracted member does not exist it 338will be created. 339If the file corresponding to an extracted member does exist, its owner 340and group will not be changed while its contents will be overwritten 341and its permissions will set to that entered in the archive. 342The file's access and modification time would be that of the time 343of extraction unless the 344.Fl o 345option was specified. 346.It Fl z 347Compress the resulting archive with 348.Xr gzip 1 . 349.El 350.Sh EXAMPLES 351To create a new archive 352.Pa ex.a 353containing three files 354.Pa ex1.o , 355.Pa ex2.o 356and 357.Pa ex3.o , 358use: 359.Dl "ar -rc ex.a ex1.o ex2.o ex3.o" 360.Pp 361To add an archive symbol table to an existing archive 362.Pa ex.a , 363use: 364.Dl "ar -s ex.a" 365.Pp 366To delete file 367.Pa ex1.o 368from archive 369.Pa ex.a , 370use: 371.D1 "ar -d ex.a ex1.o" 372.Pp 373To verbosely list the contents of archive 374.Pa ex.a , 375use: 376.D1 "ar -tv ex.a" 377.Sh DIAGNOSTICS 378.Ex -std 379.Sh SEE ALSO 380.Xr ld 1 , 381.Xr archive 3 , 382.Xr elf 3 , 383.Xr strftime 3 , 384.Xr strmode 3 , 385.Xr ar 5 386.\" .Sh COMPATIBILITY 387.\" .Nm 388.\" is expected to be compatible with GNU and SVR4 389.\" .Nm . 390.\" .Sh STANDARDS 391.\" Do the POSIX/SuSv3 standards have anything to say about AR(1)? 392.Sh HISTORY 393An 394.Nm 395command first appeared in AT&T UNIX Version 1. 396In 397.Fx 8.0 , 398.An "Kai Wang" Aq kaiw@FreeBSD.org 399reimplemented 400.Nm 401and 402.Nm ranlib 403using the 404.Lb libarchive 405and the 406.Lb libelf . 407