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