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