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