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 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 189This option is accepted but ignored. 190.It Fl m 191Move archive members specified by arguments 192.Ar files ... 193within the archive. 194If a position has been specified by one of the 195.Fl a , 196.Fl b 197or 198.Fl i 199options, the members are moved to before or after the specified 200position. 201If no position has been specified, the specified members are moved 202to the end of the archive. 203If the archive has a symbol table, it is updated to reflect the 204new contents of the archive. 205.It Fl o 206Preserve the original modification times of members when extracting 207them. 208.It Fl p 209Write the contents of the specified archive members named by 210arguments 211.Ar files ... 212to standard output. 213If no members were specified, the contents of all the files in the 214archive are written in the order they appear in the archive. 215.It Fl q 216Append the files specified by arguments 217.Ar files ... 218to the archive specified by argument 219.Ar archive 220without checking if the files already exist in the archive and 221without updating the archive's symbol table. 222If the archive file 223.Ar archive 224does not already exist, a new archive is created. 225However, to be compatible with GNU 226.Nm , 227option 228.Fl q 229will update the archive's symbol table. 230.It Fl r 231Replace (add) the files specified by arguments 232.Ar files ... 233in the archive specified by argument 234.Ar archive , 235creating the archive if necessary. 236Files that replace existing files do not change the order of files 237within the archive. 238If a file named in arguments 239.Ar files ... 240does not exist, existing members in the archive that match that 241name are not changed. 242New files are added to the end of the archive unless one of the 243positioning options 244.Fl a , 245.Fl b 246or 247.Fl i 248is specified. 249The archive symbol table, if it exists, is updated to reflect the 250new state of the archive. 251.It Fl s 252Add an archive symbol table (see 253.Xr ar 5 ) 254to the archive specified by argument 255.Ar archive . 256Invoking 257.Nm 258with the 259.Fl s 260option alone is equivalent to invoking 261.Nm ranlib . 262.It Fl t 263List the files specified by arguments 264.Ar files ... 265in the order in which they appear in the archive, one per line. 266If no files are specified, all files in the archive are listed. 267.It Fl T 268Use only the first fifteen characters of the archive member name or 269command line file name argument when naming archive members. 270.It Fl u 271Conditionally update the archive or extract members. 272When used with the 273.Fl r 274option, files named by arguments 275.Ar files ... 276will be replaced in the archive if they are newer than their 277archived versions. 278When used with the 279.Fl x 280option, the members specified by arguments 281.Ar files ... 282will be extracted only if they are newer than the corresponding 283files in the file system. 284.It Fl v 285Provide verbose output. 286When used with the 287.Fl d , 288.Fl m , 289.Fl q 290or 291.Fl x 292options, 293.Nm 294gives a file-by-file description of the archive modification being 295performed, which consists of three white-space separated fields: 296the option letter, a dash 297.Dq "-" , 298and the file name. 299When used with the 300.Fl r 301option, 302.Nm 303displays the description as above, but the initial letter is an 304.Dq a 305if the file is added to the archive, or an 306.Dq r 307if the file replaces a file already in the archive. 308When used with the 309.Fl p 310option, the name of the file enclosed in 311.Dq < 312and 313.Dq > 314characters is written to standard output preceded by a single newline 315character and followed by two newline characters. 316The contents of the named file follow the file name. 317When used with the 318.Fl t 319option, 320.Nm 321displays eight whitespace separated fields: 322the file permissions as displayed by 323.Xr strmode 3 , 324decimal user and group IDs separated by a slash ( 325.Dq / Ns ) , 326the file size in bytes, the file modification time in 327.Xr strftime 3 328format 329.Dq "%b %e %H:%M %Y" , 330and the name of the file. 331.It Fl x 332Extract archive members specified by arguments 333.Ar files ... 334into the current directory. 335If no members have been specified, extract all members of the archive. 336If the file corresponding to an extracted member does not exist it 337will be created. 338If the file corresponding to an extracted member does exist, its owner 339and group will not be changed while its contents will be overwritten 340and its permissions will set to that entered in the archive. 341The file's access and modification time would be that of the time 342of extraction unless the 343.Fl o 344option was specified. 345.It Fl z 346This option is accepted but ignored. 347.El 348.Sh EXAMPLES 349To create a new archive 350.Pa ex.a 351containing three files 352.Pa ex1.o , 353.Pa ex2.o 354and 355.Pa ex3.o , 356use: 357.Dl "ar -rc ex.a ex1.o ex2.o ex3.o" 358.Pp 359To add an archive symbol table to an existing archive 360.Pa ex.a , 361use: 362.Dl "ar -s ex.a" 363.Pp 364To delete file 365.Pa ex1.o 366from archive 367.Pa ex.a , 368use: 369.D1 "ar -d ex.a ex1.o" 370.Pp 371To verbosely list the contents of archive 372.Pa ex.a , 373use: 374.D1 "ar -tv ex.a" 375.Sh DIAGNOSTICS 376.Ex -std 377.Sh SEE ALSO 378.Xr ld 1 , 379.Xr archive 3 , 380.Xr elf 3 , 381.Xr strftime 3 , 382.Xr strmode 3 , 383.Xr ar 5 384.\" .Sh COMPATIBILITY 385.\" .Nm 386.\" is expected to be compatible with GNU and SVR4 387.\" .Nm . 388.\" .Sh STANDARDS 389.\" Do the POSIX/SuSv3 standards have anything to say about AR(1)? 390.Sh HISTORY 391An 392.Nm 393command first appeared in AT&T UNIX Version 1. 394In 395.Fx 8.0 , 396.An "Kai Wang" Aq kaiw@FreeBSD.org 397reimplemented 398.Nm 399and 400.Nm ranlib 401using the 402.Lb libarchive 403and the 404.Lb libelf . 405