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 September 24, 2015
  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, insert 0's instead of the real mtime, uid and gid values
 209 and 0644 instead of file mode from the members named by arguments
 210 .Ar .
 211 This ensures that checksums on the resulting archives are reproducible
 212 when member contents are identical.
 213 This option is enabled by default.
 214 If multiple
 215 .Fl D
 216 and
 217 .Fl U
 218 options are specified on the command line, the final one takes precedence.
 219 .It Fl f
 220 Synonymous with option
 221 .Fl T .
 222 .It Fl i Ar member-before
 223 Synonymous with option
 224 .Fl b .
 225 .It Fl j
 226 This option is accepted but ignored.
 227 .It Fl l
 228 This option is accepted for compatibility with GNU
 229 .Xr ar 1 ,
 230 but is ignored.
 231 .It Fl m
 232 Move archive members specified by arguments
 233 .Ar
 234 within the archive.
 235 If a position has been specified by one of the
 236 .Fl a ,
 237 .Fl b
 238 or
 239 .Fl i
 240 options, the members are moved to before or after the specified
 241 position.
 242 If no position has been specified, the specified members are moved
 243 to the end of the archive.
 244 If the archive has a symbol table, it is updated to reflect the
 245 new contents of the archive.
 246 .It Fl M
 247 Read and execute MRI librarian commands from standard input.
 248 The commands understood by the
 249 .Nm
 250 utility are described in the section
 251 .Sx "MRI Librarian Commands" .
 252 .It Fl o
 253 Preserve the original modification times of members when extracting
 254 them.
 255 .It Fl p
 256 Write the contents of the specified archive members named by
 257 arguments
 258 .Ar
 259 to standard output.
 260 If no members were specified, the contents of all the files in the
 261 archive are written in the order they appear in the archive.
 262 .It Fl q
 263 Append the files specified by arguments
 264 .Ar
 265 to the archive specified by argument
 266 .Ar archive
 267 without checking if the files already exist in the archive.
 268 The archive symbol table will be updated as needed.
 269 If the file specified by the argument
 270 .Ar archive
 271 does not already exist, a new archive will be created.
 272 .It Fl r
 273 Replace (add) the files specified by arguments
 274 .Ar
 275 in the archive specified by argument
 276 .Ar archive ,
 277 creating the archive if necessary.
 278 Replacing existing members will not change the order of members within
 279 the archive.
 280 If a file named in arguments
 281 .Ar
 282 does not exist, existing members in the archive that match that
 283 name are not changed.
 284 New files are added to the end of the archive unless one of the
 285 positioning options
 286 .Fl a ,
 287 .Fl b
 288 or
 289 .Fl i
 290 is specified.
 291 The archive symbol table, if it exists, is updated to reflect the
 292 new state of the archive.
 293 .It Fl s
 294 Add an archive symbol table (see
 295 .Xr ar 5 )
 296 to the archive specified by argument
 297 .Ar archive .
 298 Invoking
 299 .Nm
 300 with the
 301 .Fl s
 302 option alone is equivalent to invoking
 303 .Nm ranlib .
 304 .It Fl S
 305 Do not generate an archive symbol table.
 306 .It Fl t
 307 List the files specified by arguments
 308 .Ar
 309 in the order in which they appear in the archive, one per line.
 310 If no files are specified, all files in the archive are listed.
 311 .It Fl T
 312 Use only the first fifteen characters of the archive member name or
 313 command line file name argument when naming archive members.
 314 .It Fl u
 315 Conditionally update the archive or extract members.
 316 When used with the
 317 .Fl r
 318 option, files named by arguments
 319 .Ar
 320 will be replaced in the archive if they are newer than their
 321 archived versions.
 322 When used with the
 323 .Fl x
 324 option, the members specified by arguments
 325 .Ar
 326 will be extracted only if they are newer than the corresponding
 327 files in the file system.
 328 .It Fl U
 329 When used in combination with the
 330 .Fl r
 331 or
 332 .Fl q
 333 option, insert the real mtime, uid and gid, and file mode values
 334 from the members named by arguments
 335 .Ar .
 336 If multiple
 337 .Fl D
 338 and
 339 .Fl U
 340 options are specified on the command line, the final one takes precedence.
 341 .It Fl v
 342 Provide verbose output.
 343 When used with the
 344 .Fl d ,
 345 .Fl m ,
 346 .Fl q
 347 or
 348 .Fl x
 349 options,
 350 .Nm
 351 gives a file-by-file description of the archive modification being
 352 performed, which consists of three white-space separated fields:
 353 the option letter, a dash
 354 .Dq "-" ,
 355 and the file name.
 356 When used with the
 357 .Fl r
 358 option,
 359 .Nm
 360 displays the description as above, but the initial letter is an
 361 .Dq a
 362 if the file is added to the archive, or an
 363 .Dq r
 364 if the file replaces a file already in the archive.
 365 When used with the
 366 .Fl p
 367 option, the name of the file enclosed in
 368 .Dq <
 369 and
 370 .Dq >
 371 characters is written to standard output preceded by a single newline
 372 character and followed by two newline characters.
 373 The contents of the named file follow the file name.
 374 When used with the
 375 .Fl t
 376 option,
 377 .Nm
 378 displays eight whitespace separated fields:
 379 the file permissions as displayed by
 380 .Xr strmode 3 ,
 381 decimal user and group IDs separated by a slash (
 382 .Dq / Ns ) ,
 383 the file size in bytes, the file modification time in
 384 .Xr strftime 3
 385 format
 386 .Dq "%b %e %H:%M %Y" ,
 387 and the name of the file.
 388 .It Fl V
 389 Print a version string and exit.
 390 .It Fl x
 391 Extract archive members specified by arguments
 392 .Ar
 393 into the current directory.
 394 If no members have been specified, extract all members of the archive.
 395 If the file corresponding to an extracted member does not exist it
 396 will be created.
 397 If the file corresponding to an extracted member does exist, its owner
 398 and group will not be changed while its contents will be overwritten
 399 and its permissions will set to that entered in the archive.
 400 The file's access and modification time would be that of the time
 401 of extraction unless the
 402 .Fl o
 403 option was specified.
 404 .It Fl z
 405 This option is accepted but ignored.
 406 .El
 407 .Ss "MRI Librarian Commands"
 408 If the
 409 .Fl M
 410 option is specified, the
 411 .Nm
 412 utility will read and execute commands from its standard input.
 413 If standard input is a terminal, the
 414 .Nm
 415 utility will display the prompt
 416 .Dq Li "AR >"
 417 before reading a line, and will continue operation even if errors are
 418 encountered.
 419 If standard input is not a terminal, the
 420 .Nm
 421 utility will not display a prompt and will terminate execution on
 422 encountering an error.
 423 .Pp
 424 Each input line contains a single command.
 425 Words in an input line are separated by whitespace characters.
 426 The first word of the line is the command, the remaining words are
 427 the arguments to the command.
 428 The command word may be specified in either case.
 429 Arguments may be separated by commas or blanks.
 430 .Pp
 431 Empty lines are allowed and are ignored.
 432 Long lines are continued by ending them with the
 433 .Dq Li +
 434 character.
 435 .Pp
 436 The
 437 .Dq Li *
 438 and
 439 .Dq Li "\&;"
 440 characters start a comment.
 441 Comments extend till the end of the line.
 442 .Pp
 443 When executing an MRI librarian script the
 444 .Nm
 445 utility works on a temporary copy of an archive.
 446 Changes to the copy are made permanent using the
 447 .Ic save
 448 command.
 449 .Pp
 450 Commands understood by the
 451 .Nm
 452 utility are:
 453 .Bl -tag -width indent
 454 .It Ic addlib Ar archive | Ic addlib Ar archive Pq Ar member Oo Li , Ar member Oc Ns ...
 455 Add the contents of the archive named by argument
 456 .Ar archive
 457 to the current archive.
 458 If specific members are named using the arguments
 459 .Ar member ,
 460 then those members are added to the current archive.
 461 If no members are specified, the entire contents of the archive
 462 are added to the current archive.
 463 .It Ic addmod Ar member Oo Li , Ar member Oc Ns ...
 464 Add the files named by arguments
 465 .Ar member
 466 to the current archive.
 467 .It Ic clear
 468 Discard all the contents of the current archive.
 469 .It Ic create Ar archive
 470 Create a new archive named by the argument
 471 .Ar archive ,
 472 and makes it the current archive.
 473 If the named archive already exists, it will be overwritten
 474 when the
 475 .Ic save
 476 command is issued.
 477 .It Ic delete Ar module Oo Li , Ar member Oc Ns ...
 478 Delete the modules named by the arguments
 479 .Ar member
 480 from the current archive.
 481 .It Ic directory Ar archive Po Ar member Oo Li , Ar member Oc Ns ... Pc Op Ar outputfile
 482 List each named module in the archive.
 483 The format of the output depends on the verbosity setting set using
 484 the
 485 .Ic verbose
 486 command.
 487 Output is sent to standard output, or to the file specified by
 488 argument
 489 .Ar outputfile .
 490 .It Ic end
 491 Exit successfully from the
 492 .Nm
 493 utility.
 494 Any unsaved changes to the current archive will be discarded.
 495 .It Ic extract Ar member Oo Li , Ar member Oc Ns ...
 496 Extract the members named by the arguments
 497 .Ar member
 498 from the current archive.
 499 .It Ic list
 500 Display the contents of the current archive in verbose style.
 501 .It Ic open Ar archive
 502 Open the archive named by argument
 503 .Ar archive
 504 and make it the current archive.
 505 .It Ic replace Ar member Oo Li , Ar member Oc Ns ...
 506 Replace named members in the current archive with the files specified
 507 by arguments
 508 .Ar member .
 509 The files must be present in the current directory and the named
 510 modules must already exist in the current archive.
 511 .It Ic save
 512 Commit all changes to the current archive.
 513 .It Ic verbose
 514 Toggle the verbosity of the
 515 .Ic directory
 516 command.
 517 .El
 518 .Sh EXAMPLES
 519 To create a new archive
 520 .Pa ex.a
 521 containing three files
 522 .Pa ex1.o ,
 523 .Pa ex2.o
 524 and
 525 .Pa ex3.o ,
 526 use:
 527 .Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
 528 .Pp
 529 To add an archive symbol table to an existing archive
 530 .Pa ex.a ,
 531 use:
 532 .Dl "ar -s ex.a"
 533 .Pp
 534 To delete file
 535 .Pa ex1.o
 536 from archive
 537 .Pa ex.a ,
 538 use:
 539 .D1 "ar -d ex.a ex1.o"
 540 .Pp
 541 To verbosely list the contents of archive
 542 .Pa ex.a ,
 543 use:
 544 .D1 "ar -tv ex.a"
 545 .Pp
 546 To create a new archive
 547 .Pa ex.a
 548 containing the files
 549 .Pa ex1.o ,
 550 and
 551 .Pa ex2.o ,
 552 using MRI librarian commands, use the following script:
 553 .Bd -literal -offset indent
 554 create ex.a              * specify the output archive
 555 addmod ex1.o ex2.o       * add modules
 556 save                     * save pending changes
 557 end                      * exit the utility
 558 .Ed
 559 .Sh DIAGNOSTICS
 560 .Ex -std
 561 .Sh SEE ALSO
 562 .Xr ld 1 ,
 563 .Xr archive 3 ,
 564 .Xr elf 3 ,
 565 .Xr strftime 3 ,
 566 .Xr strmode 3 ,
 567 .Xr ar 5
 568 .Sh STANDARDS COMPLIANCE
 569 The
 570 .Nm
 571 utility's support for the
 572 .Fl a ,
 573 .Fl b ,
 574 .Fl c ,
 575 .Fl i ,
 576 .Fl m ,
 577 .Fl p ,
 578 .Fl q ,
 579 .Fl r ,
 580 .Fl s ,
 581 .Fl t ,
 582 .Fl u ,
 583 .Fl v ,
 584 .Fl C
 585 and
 586 .Fl T
 587 options is believed to be compliant with
 588 .St -p1003.2 .
 589 .Sh HISTORY
 590 An
 591 .Nm
 592 command first appeared in AT&T UNIX Version 1.
 593 In
 594 .Fx 8.0 ,
 595 .An "Kai Wang" Aq kaiw@FreeBSD.org
 596 reimplemented
 597 .Nm
 598 and
 599 .Nm ranlib
 600 using the
 601 .Lb libarchive
 602 and the
 603 .Lb libelf .