usr.bin/ar/ar.1

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