1.\" Copyright (c) 2007,2009-2012 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.\" $Id: ar.1 3230 2015-07-27 17:11:38Z emaste $ 25.\" 26.Dd July 27, 2015 27.Os 28.Dt AR 1 29.Sh NAME 30.Nm ar 31.Nd manage archives 32.Sh SYNOPSIS 33.Nm 34.Fl d 35.Op Fl T 36.Op Fl f 37.Op Fl j 38.Op Fl v 39.Op Fl z 40.Ar archive 41.Ar 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 f 48.Op Fl i Ar position-before 49.Op Fl j 50.Op Fl s | Fl S 51.Op Fl z 52.Ar archive 53.Ar 54.Nm 55.Fl p 56.Op Fl T 57.Op Fl f 58.Op Fl v 59.Ar archive 60.Op Ar 61.Nm 62.Fl q 63.Op Fl T 64.Op Fl c 65.Op Fl D 66.Op Fl f 67.Op Fl F Ar flavor | Fl -flavor Ar flavor 68.Op Fl s | Fl S 69.Op Fl U 70.Op Fl v 71.Op Fl z 72.Ar archive 73.Ar 74.Nm 75.Fl r 76.Op Fl T 77.Op Fl a Ar position-after 78.Op Fl b Ar position-before 79.Op Fl c 80.Op Fl D 81.Op Fl f 82.Op Fl F Ar flavor | Fl -flavor Ar flavor 83.Op Fl i Ar position-before 84.Op Fl j 85.Op Fl s | Fl S 86.Op Fl u 87.Op Fl U 88.Op Fl v 89.Op Fl z 90.Ar archive 91.Ar 92.Nm 93.Fl s 94.Op Fl D 95.Op Fl j 96.Op Fl U 97.Op Fl z 98.Ar archive 99.Nm 100.Fl t 101.Op Fl f 102.Op Fl T 103.Op Fl v 104.Ar archive 105.Op Ar 106.Nm 107.Fl x 108.Op Fl C 109.Op Fl T 110.Op Fl f 111.Op Fl o 112.Op Fl u 113.Op Fl v 114.Ar archive 115.Op Ar 116.Nm 117.Fl M 118.Nm 119.Fl V 120.Sh DESCRIPTION 121The 122.Nm 123utility creates and maintains groups of files combined into an 124archive. 125Once an archive has been created, new files can be added to it, and 126existing files can be extracted, deleted or replaced. 127.Pp 128Files are named in the archive by their last file name component, 129so if a file referenced by a path containing a 130.Dq / 131is archived, it will be named by the last component of the path. 132Similarly when matching paths listed on the command line against 133file names stored in the archive, only the last component of the 134path will be compared. 135.Pp 136The normal use of 137.Nm 138is for the creation and maintenance of libraries suitable for use 139with the link editor 140.Xr ld 1 , 141although it is not restricted to this purpose. 142The 143.Nm 144utility can create and manage an archive symbol table (see 145.Xr ar 5 ) 146used to speed up link editing operations. 147If a symbol table is present in an archive, it will be 148kept up-to-date by subsequent operations on the archive. 149.Sh OPTIONS 150The 151.Nm 152utility supports the following options: 153.Bl -tag -width indent 154.It Fl a Ar member-after 155When used with option 156.Fl m 157this option specifies that the archive members specified by 158arguments 159.Ar 160are moved to after the archive member named by argument 161.Ar member-after . 162When used with option 163.Fl r 164this option specifies that the files specified by arguments 165.Ar 166are added after the archive member named by argument 167.Ar member-after . 168.It Fl b Ar member-before 169When used with option 170.Fl m 171this option specifies that the archive members specified by 172arguments 173.Ar 174are moved to before the archive member named by argument 175.Ar member-before . 176When used with option 177.Fl r 178this option specifies that the files specified by arguments 179.Ar 180are added before the archive member named by argument 181.Ar member-before . 182.It Fl c 183Suppress the informational message printed when a new archive is 184created using the 185.Fl r 186and 187.Fl q 188options. 189.It Fl C 190Prevent extracted files from replacing like-named files 191in the file system. 192.It Fl d 193Delete the members named by arguments 194.Ar 195from the archive specified by argument 196.Ar archive . 197The archive's symbol table, if present, is updated to reflect 198the new contents of the archive. 199.It Fl D 200When used in combination with the 201.Fl r 202or 203.Fl q 204option, insert 0's instead of the real mtime, uid and gid values 205and 0644 instead of file mode from the members named by arguments 206.Ar . 207This ensures that checksums on the resulting archives are reproducible 208when member contents are identical. 209If multiple 210.Fl D 211and 212.Fl U 213options are specified on the command line, the final one takes precedence. 214.It Fl f 215Synonymous with option 216.Fl T . 217.It Fl F Ar flavor | Fl -flavor Ar flavor 218Create archives with the specified archive format. 219Legal values for argument 220.Ar flavor 221are: 222.Bl -tag -width indent -compact 223.It Ar bsd 224Create BSD format archives. 225.It Ar gnu 226An alias for 227.Ar svr4 . 228.It Ar svr4 229Create SVR4 format archives. 230.El 231If this option is not specified, 232.Nm 233will create archives using the SVR4 format. 234.It Fl i Ar member-before 235Synonymous with option 236.Fl b . 237.It Fl j 238This option is accepted for compatibility with the 239.Tn FreeBSD 240version of the 241.Nm 242utility, but is ignored. 243.It Fl l 244This option is accepted for compatibility with GNU 245.Xr ar 1 , 246but is ignored. 247.It Fl m 248Move archive members specified by arguments 249.Ar 250within the archive. 251If a position has been specified by one of the 252.Fl a , 253.Fl b 254or 255.Fl i 256options, the members are moved to before or after the specified 257position. 258If no position has been specified, the specified members are moved 259to the end of the archive. 260If the archive has a symbol table, it is updated to reflect the 261new contents of the archive. 262.It Fl M 263Read and execute MRI librarian commands from standard input. 264The commands understood by the 265.Nm 266utility are described in the section 267.Sx "MRI Librarian Commands" . 268.It Fl o 269Preserve the original modification times of members when extracting 270them. 271.It Fl p 272Write the contents of the specified archive members named by 273arguments 274.Ar 275to standard output. 276If no members were specified, the contents of all the files in the 277archive are written in the order they appear in the archive. 278.It Fl q 279Append the files specified by arguments 280.Ar 281to the archive specified by argument 282.Ar archive 283without checking if the files already exist in the archive. 284The archive symbol table will be updated as needed. 285If the file specified by the argument 286.Ar archive 287does not already exist, a new archive will be created. 288.It Fl r 289Replace (add) the files specified by arguments 290.Ar 291in the archive specified by argument 292.Ar archive , 293creating the archive if necessary. 294Replacing existing members will not change the order of members within 295the archive. 296If a file named in arguments 297.Ar 298does not exist, existing members in the archive that match that 299name are not changed. 300New files are added to the end of the archive unless one of the 301positioning options 302.Fl a , 303.Fl b 304or 305.Fl i 306is specified. 307The archive symbol table, if it exists, is updated to reflect the 308new state of the archive. 309.It Fl s 310Add an archive symbol table (see 311.Xr ar 5 ) 312to the archive specified by argument 313.Ar archive . 314Invoking 315.Nm 316with the 317.Fl s 318option alone is equivalent to invoking 319.Xr ranlib 1 . 320.It Fl S 321Do not generate an archive symbol table. 322.It Fl t 323For 324.Nm , 325list the files specified by arguments 326.Ar 327in the order in which they appear in the archive, one per line. 328If no files are specified, all files in the archive are listed. 329.It Fl T 330Use only the first fifteen characters of the archive member name or 331command line file name argument when naming archive members. 332.It Fl u 333Conditionally update the archive or extract members. 334When used with the 335.Fl r 336option, files named by arguments 337.Ar 338will be replaced in the archive if they are newer than their 339archived versions. 340When used with the 341.Fl x 342option, the members specified by arguments 343.Ar 344will be extracted only if they are newer than the corresponding 345files in the file system. 346.It Fl U 347When used in combination with the 348.Fl r 349or 350.Fl q 351option, insert the real mtime, uid and gid, and file mode values 352from the members named by arguments 353.Ar . 354If multiple 355.Fl D 356and 357.Fl U 358options are specified on the command line, the final one takes precedence. 359.It Fl v 360Provide verbose output. 361When used with the 362.Fl d , 363.Fl m , 364.Fl q 365or 366.Fl x 367options, 368.Nm 369gives a file-by-file description of the archive modification being 370performed, which consists of three white-space separated fields: 371the option letter, a dash 372.Dq "-" , 373and the file name. 374When used with the 375.Fl r 376option, 377.Nm 378displays the description as above, but the initial letter is an 379.Dq a 380if the file is added to the archive, or an 381.Dq r 382if the file replaces a file already in the archive. 383When used with the 384.Fl p 385option, the name of the file enclosed in 386.Dq < 387and 388.Dq > 389characters is written to standard output preceded by a single newline 390character and followed by two newline characters. 391The contents of the named file follow the file name. 392When used with the 393.Fl t 394option, 395.Nm 396displays eight whitespace separated fields: 397the file permissions as displayed by 398.Xr strmode 3 , 399decimal user and group IDs separated by a slash ( 400.Dq / Ns ) , 401the file size in bytes, the file modification time in 402.Xr strftime 3 403format 404.Dq "%b %e %H:%M %Y" , 405and the name of the file. 406.It Fl V 407Print a version identifier and exit. 408.It Fl x 409Extract archive members specified by arguments 410.Ar 411into the current directory. 412If no members have been specified, extract all members of the archive. 413If the file corresponding to an extracted member does not exist it 414will be created. 415If the file corresponding to an extracted member does exist, its owner 416and group will not be changed while its contents will be overwritten 417and its permissions will set to that entered in the archive. 418The file's access and modification time would be that of the time 419of extraction unless the 420.Fl o 421option was specified. 422.It Fl z 423This option is accepted for compatibility with the 424.Tn FreeBSD 425version of the 426.Nm 427utility, but is ignored. 428.El 429.Ss "MRI Librarian Commands" 430If the 431.Fl M 432option is specified, the 433.Nm 434utility will read and execute commands from its standard input. 435If standard input is a terminal, the 436.Nm 437utility will display the prompt 438.Dq Li "AR >" 439before reading a line, and will continue operation even if errors are 440encountered. 441If standard input is not a terminal, the 442.Nm 443utility will not display a prompt and will terminate execution on 444encountering an error. 445.Pp 446Each input line contains a single command. 447Words in an input line are separated by whitespace characters. 448The first word of the line is the command, the remaining words are 449the arguments to the command. 450The command word may be specified in either case. 451Arguments may be separated by commas or blanks. 452.Pp 453Empty lines are allowed and are ignored. 454Long lines are continued by ending them with the 455.Dq Li + 456character. 457.Pp 458The 459.Dq Li * 460and 461.Dq Li "\;" 462characters start a comment. 463Comments extend till the end of the line. 464.Pp 465When executing an MRI librarian script the 466.Nm 467utility works on a temporary copy of an archive. 468Changes to the copy are made permanent using the 469.Ic save 470command. 471.Pp 472Commands understood by the 473.Nm 474utility are: 475.Bl -tag -width indent 476.It Ic addlib Ar archive | Ic addlib Ar archive Pq Ar member Oo Li , Ar member Oc Ns ... 477Add the contents of the archive named by argument 478.Ar archive 479to the current archive. 480If specific members are named using the arguments 481.Ar member , 482then those members are added to the current archive. 483If no members are specified, the entire contents of the archive 484are added to the current archive. 485.It Ic addmod Ar member Oo Li , Ar member Oc Ns ... 486Add the files named by arguments 487.Ar member 488to the current archive. 489.It Ic clear 490Discard all the contents of the current archive. 491.It Ic create Ar archive 492Create a new archive named by the argument 493.Ar archive , 494and makes it the current archive. 495If the named archive already exists, it will be overwritten 496when the 497.Ic save 498command is issued. 499.It Ic delete Ar module Oo Li , Ar member Oc Ns ... 500Delete the modules named by the arguments 501.Ar member 502from the current archive. 503.It Ic directory Ar archive Po Ar member Oo Li , Ar member Oc Ns ... Pc Op Ar outputfile 504List each named module in the archive. 505The format of the output depends on the verbosity setting set using 506the 507.Ic verbose 508command. 509Output is sent to standard output, or to the file specified by 510argument 511.Ar outputfile . 512.It Ic end 513Exit successfully from the 514.Nm 515utility. 516Any unsaved changes to the current archive will be discarded. 517.It Ic extract Ar member Oo Li , Ar member Oc Ns ... 518Extract the members named by the arguments 519.Ar member 520from the current archive. 521.It Ic list 522Display the contents of the current archive in verbose style. 523.It Ic open Ar archive 524Open the archive named by argument 525.Ar archive 526and make it the current archive. 527.It Ic replace Ar member Oo Li , Ar member Oc Ns ... 528Replace named members in the current archive with the files specified 529by arguments 530.Ar member . 531The files must be present in the current directory and the named 532modules must already exist in the current archive. 533.It Ic save 534Commit all changes to the current archive. 535.It Ic verbose 536Toggle the verbosity of the 537.Ic directory 538command. 539.El 540.Sh EXAMPLES 541To create a new archive 542.Pa ex.a 543containing three files 544.Pa ex1.o , 545.Pa ex2.o 546and 547.Pa ex3.o , 548use: 549.Dl "ar -rc ex.a ex1.o ex2.o ex3.o" 550.Pp 551To add an archive symbol table to an existing archive 552.Pa ex.a , 553use: 554.Dl "ar -s ex.a" 555.Pp 556To delete file 557.Pa ex1.o 558from archive 559.Pa ex.a , 560use: 561.D1 "ar -d ex.a ex1.o" 562.Pp 563To verbosely list the contents of archive 564.Pa ex.a , 565use: 566.D1 "ar -tv ex.a" 567.Pp 568To create a new archive 569.Pa ex.a 570containing the files 571.Pa ex1.o , 572and 573.Pa ex2.o , 574using MRI librarian commands, use the following script: 575.Bd -literal -offset indent 576create ex.a * specify the output archive 577addmod ex1.o ex2.o * add modules 578save * save pending changes 579end * exit the utility 580.Ed 581.Sh DIAGNOSTICS 582.Ex -std 583.Sh SEE ALSO 584.Xr ld 1 , 585.Xr ranlib 1 , 586.Xr archive 3 , 587.Xr elf 3 , 588.Xr strftime 3 , 589.Xr strmode 3 , 590.Xr ar 5 591.Sh STANDARDS COMPLIANCE 592The 593.Nm 594utility's support for the 595.Fl a , 596.Fl b , 597.Fl c , 598.Fl i , 599.Fl m , 600.Fl p , 601.Fl q , 602.Fl r , 603.Fl s , 604.Fl t , 605.Fl u , 606.Fl v , 607.Fl C 608and 609.Fl T 610options is believed to be compliant with 611.St -p1003.2 . 612.Sh HISTORY 613An 614.Nm 615command first appeared in AT&T UNIX Version 1. 616In 617.Fx 8.0 , 618.An Kai Wang Aq Mt kaiw@FreeBSD.org 619reimplemented 620.Nm 621using the 622.Lb libarchive 623and the 624.Lb libelf . 625