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