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