contrib/elftoolchain/ar/ar.1

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