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