cde/programs/dtksh/ksh93/src/cmd/pax/pax.1

   1 .\" $XConsortium: pax.1 /main/3 1995/11/01 17:01:42 rswiston $
   2 .\"
   3 .\" Glenn Fowler
   4 .\" AT&T Bell Laboratories
   5 .\"
   6 .\" @(#)pax.1 (gsf@research.att.com) 01/11/95
   7 .\"
   8 .TH PAX 1
   9 .SH NAME
  10 pax \- portable archive interchange
  11 .SH SYNOPSIS
  12 .B pax
  13 [
  14 .B \-r
  15 ] [
  16 .B \-v
  17 ] [
  18 .B \-f
  19 .I archive
  20 ] [
  21 .B \-s
  22 .RI / old / new /[glpsu]
  23 ] [
  24 .B \-z
  25 .I base
  26 ] [
  27 .I "pattern ..."
  28 ]
  29 .LP
  30 .B pax
  31 .B \-w
  32 [
  33 .B \-a
  34 ] [
  35 .B \-v
  36 ] [
  37 .B \-f
  38 .I archive
  39 ] [
  40 .B \-s
  41 .RI / old / new /[glpsu]
  42 ] [
  43 .B \-x
  44 .I format
  45 ] [
  46 .B \-z
  47 .I base
  48 ] [
  49 .I "pathname ..."
  50 ]
  51 .LP
  52 .B pax
  53 .B \-rw
  54 [
  55 .B \-v
  56 ] [
  57 .B \-s
  58 .RI / old / new /[glpsu]
  59 ] [
  60 .I "pathname ..."
  61 ]
  62 .I directory
  63 .SH DESCRIPTION
  64 .I pax
  65 reads and writes archive files in various formats.
  66 There are four operation modes controlled by combinations of the
  67 .B \-r
  68 and
  69 .B \-w
  70 options.
  71 .PP
  72 .B "pax \-w"
  73 writes the files and directories named by the
  74 .I pathname
  75 arguments to the standard output together with
  76 pathname and status information.
  77 A directory
  78 .I pathname
  79 argument refers to the files and (recursively) subdirectories
  80 of that directory.
  81 If no
  82 .I pathname
  83 arguments are given then the standard input is read to get
  84 a list of pathnames to copy, one pathname per line.
  85 In this case only those pathnames appearing on the standard input are copied.
  86 .PP
  87 .B "pax \-r"
  88 reads files from the standard input that is assumed
  89 to be the result of a previous
  90 .B "pax \-w"
  91 command.
  92 Only files with names that match any of the
  93 .I pattern
  94 arguments are selected.
  95 A
  96 .I pattern
  97 is given in the name-generating notation of
  98 .IR sh (1),
  99 except that the
 100 .B /
 101 character is also matched.
 102 The default if no
 103 .I pattern
 104 is given is
 105 .BR * ,
 106 which selects all files.
 107 The selected files are conditionally created and copied relative
 108 to the current directory tree, subject to the options described below.
 109 By default the owner and group of selected files will be that of the
 110 current user, and the permissions and modify times will be the same
 111 as those in the archive.
 112 If the
 113 .B \-r
 114 option is omitted then a table of contents of the selected files is
 115 listed on the standard output.
 116 .PP
 117 .B "pax \-rw"
 118 reads the files and directories named in the
 119 .I pathname
 120 arguments and copies them to the destination
 121 .IR directory .
 122 A directory
 123 .I pathname
 124 argument refers to the files and (recursively) subdirectories
 125 of that directory.
 126 If no
 127 .I pathname
 128 arguments are given then the standard input is read to get
 129 a list of pathnames to copy, one pathname per line.
 130 In this case only those pathnames appearing on the standard input are copied.
 131 .I directory
 132 must exist before the copy.
 133 .PP
 134 The standard archive formats are automatically detected on input.
 135 The default output archive format is implementation defined,
 136 but may be overridden by the
 137 .B \-x
 138 option described below.
 139 .I pax
 140 archives may be concatenated to combine multiple volumes on a single
 141 tape or file.
 142 This is accomplished by forcing any format prescribed pad data to be null bytes.
 143 Hard links are not maintained between volumes, and
 144 delta and base archives cannot be multi-volume.
 145 .PP
 146 A single archive may span many files/devices.
 147 The second and subsequent file names are prompted for on the terminal input.
 148 The response may be:
 149 .TP
 150 .BI ! command
 151 Execute
 152 .I command
 153 via
 154 .IR system (3)
 155 and prompt again for file name.
 156 .TP
 157 .B EOF
 158 Exit without further processing.
 159 .TP
 160 .B CR
 161 An empty input line retains the previous file name.
 162 .TP
 163 .I pathname
 164 The file name for the next archive part.
 165 .SS "Basic Options"
 166 .TP
 167 .B a
 168 For
 169 .BR \-w ,
 170 append files to the end of the archive.
 171 .TP
 172 .BI f " archive"
 173 .I archive
 174 is the pathname of the input or output archive, overriding the default
 175 standard input for
 176 .B \-r
 177 and
 178 .B \-rw
 179 or standard output for
 180 .BR \-w .
 181 .TP
 182 \fBs\fP /\fIold\fP/\fInew\fP/[\fBglpu\fP]
 183 File names and symbolic link text are mapped according
 184 to the
 185 .IR ed (1)
 186 style substitution expression.
 187 Any non-null character may be used as a delimiter
 188 .RB ( /
 189 shown here).
 190 Multiple
 191 .B \-s
 192 expressions may be specified; the expressions are applied from left to right.
 193 A trailing
 194 .B l
 195 converts the matched string to lower case.
 196 A trailing
 197 .B p
 198 causes successful mappings to be listed on the standard error.
 199 A trailing
 200 .B s
 201 stops the substitutions on the current name if the substitution
 202 changes the name.
 203 A trailing
 204 .B u
 205 converts the matched string to upper case.
 206 File names that substitute to the null string are ignored on
 207 both input and output.
 208 The
 209 .B "\-o physical"
 210 option inhibits symbolic link text substitution.
 211 .TP
 212 .B v
 213 Produces a verbose table of contents listing on the standard output when both
 214 .B \-r
 215 and
 216 .B \-w
 217 are omitted.
 218 Otherwise the file names are listed on the standard error
 219 as they are encountered.
 220 .TP
 221 .BI x " format"
 222 Specifies the output archive
 223 .IR format .
 224 If specified with
 225 .B \-rw
 226 then the standard input is treated as an archive that is converted to a
 227 .I format
 228 archive on the standard output.
 229 The input format, which must be one of the following,
 230 is automatically determined.
 231 The default output format, named by
 232 .BR \- ,
 233 is currently
 234 .BR cpio .
 235 The formats are:
 236 .RS
 237 .PD 0
 238 .TP
 239 .B ansi
 240 ANSI standard label tape format.
 241 Only regular files with simple pathnames are archived.
 242 Valid only for blocked devices.
 243 .TP
 244 .B asc
 245 The
 246 .B s5r4
 247 extended
 248 .IR cpio (5)
 249 character format.
 250 .TP
 251 .B aschk
 252 The
 253 .B s5r4
 254 extended
 255 .IR cpio (5)
 256 character format with header checksum.
 257 This format is misnamed
 258 .B crc
 259 in the
 260 .B s5r4
 261 documentation.
 262 .TP
 263 .B binary
 264 The
 265 .IR cpio (5)
 266 binary format with symbolic links.
 267 This format is obsolete and should not be used on output.
 268 .TP
 269 .B cpio
 270 The
 271 .IR cpio (5)
 272 character format with symbolic links.
 273 This is the default output format.
 274 .TP
 275 .B ibmar
 276 EBCDIC standard label tape format.
 277 Only regular files with simple pathnames are archived.
 278 Valid only for tape devices.
 279 .TP
 280 .B posix
 281 The IEEE 1003.1b-1990 interchange format, partially compatible with
 282 the X3.27 standard labeled tape format.
 283 .TP
 284 .B portarch
 285 The s5r2 portable object library format.
 286 Valid only on input.
 287 .TP
 288 .B randarch
 289 The BSD ranlib object library format.
 290 Valid only on input.
 291 .TP
 292 .B tar
 293 The
 294 .IR tar (5)
 295 format with symbolic links.
 296 .TP
 297 .B ustar
 298 The POSIX IEEE Std 1003.1-1988 tar format.
 299 .TP
 300 .B vdb
 301 The
 302 .I "virtual database"
 303 format used by
 304 .IR cia (1)
 305 and
 306 .IR cql (1).
 307 .TP
 308 .B vmsbackup
 309 ANSI standard label VMS backup savset tape format.
 310 Valid only for input tape devices.
 311 .TP
 312 .I format
 313 Formats can be defined as extensions to the builtin formats.
 314 For any non-builtin format
 315 .IR format ,
 316 can be
 317 .PD
 318 .RE
 319 .SS "Extended Options"
 320 All options have long string names specified using
 321 .B \-o
 322 .RI [no] name [= value ];
 323 .TP
 324 .B append
 325 .RB ( \-a )
 326 For
 327 .BR \-w ,
 328 append files to the end of the archive.
 329 .TP
 330 .B atime
 331 Preserve the access time of all files.
 332 .TP
 333 .BI base =path
 334 .RB ( \-z )
 335 .BI b " blocking"
 336 Set the output blocking size.
 337 If no suffix (or a
 338 .B c
 339 suffix) is specified then
 340 .I blocking
 341 is in 1 character units.
 342 A
 343 .B b
 344 suffix multiplies
 345 .I blocking
 346 by 512 (1 block), a
 347 .B k
 348 suffix multiplies
 349 .I blocking
 350 by 1024 (1 kilobyte) and an
 351 .B m
 352 suffix multiplies
 353 .I blocking
 354 by 1048576 (1 megabyte).
 355 .I blocking
 356 is automatically determined on input and is ignored for
 357 .BR \-rw .
 358 The default
 359 .I blocking
 360 is
 361 .B 10k
 362 for block and character special archive files and
 363 implementation defined otherwise.
 364 The minimum
 365 .I blocking
 366 is
 367 .BR 1c .
 368 .TP
 369 .B exact
 370 .RB ( \-n )
 371 For
 372 .B \-r
 373 the pattern arguments are treated as ordinary file names.
 374 Only the first occurrence of each of these files in the
 375 input archive is read.
 376 .I pax
 377 exits with zero exit status after all files in the list have been read.
 378 If one or more files in the list is not found,
 379 .I pax
 380 writes a message to standard error for each of these files
 381 and exits with a non-zero exit status.
 382 The file names are compared before any pathname transformations are applied.
 383 .TP
 384 .B m
 385 File modification times are not retained.
 386 .TP
 387 .B o
 388 Restore file ownership as specified in the archive.
 389 The current user must have appropriate privileges.
 390 .SS "Compatibility Options"
 391 These options provide functional compatibility with the old
 392 .IR cpio (1)
 393 and
 394 .IR tar (1)
 395 commands.
 396 .TP
 397 .B c
 398 Complement the match sense of the
 399 .I pattern
 400 arguments.
 401 .TP
 402 .B d
 403 Intermediate directories not explicitly listed in the archive
 404 are not created.
 405 .TP
 406 .B i
 407 Interactively
 408 .I rename
 409 files.
 410 A file is skipped if a null line is entered and
 411 .I pax
 412 exits if
 413 .B EOF
 414 is encountered.
 415 .TP
 416 .B l
 417 For
 418 .BR \-rw ,
 419 files are linked rather than copied when possible.
 420 .TP
 421 .B p
 422 Preserve the access times of input files after they have been copied.
 423 .TP
 424 .BI t " device"
 425 .I device
 426 is an identifier that names the input or output archive device,
 427 overriding the default standard input for
 428 .B \-r
 429 or standard output for
 430 .BR \-w .
 431 Tape devices may be specified as
 432 .IR drive [ density\|rewind ]
 433 where
 434 .I drive
 435 is a drive number in the range [0\-7],
 436 .I density
 437 is one of
 438 .BR l ,
 439 .B m
 440 and
 441 .B h
 442 for
 443 .B low
 444 (800 bpi),
 445 .B medium
 446 (1600 bpi \- default)
 447 and
 448 .B high
 449 (6250 bpi)
 450 tape densities and
 451 .I rewind
 452 is
 453 .B n
 454 to inhibit rewinding of the tape device when it is closed.
 455 Other forms for
 456 .I device
 457 are implementation defined.
 458 .TP
 459 .B u
 460 Copy each file only if it is newer than a pre-existing file with the same name.
 461 This option implies
 462 .BR \-a .
 463 .TP
 464 .B y
 465 Interactively prompt for the disposition of each file.
 466 .B EOF
 467 or an input line starting with
 468 .B q
 469 causes
 470 .I pax
 471 to exit.
 472 Otherwise an input line starting with anything other than
 473 .B y
 474 causes the file to be ignored.
 475 .SS "Extended Options"
 476 These options provide fine archive control, including delta archive operations.
 477 .TP
 478 .BI e " filter"
 479 Run the
 480 .I filter
 481 command on each file to be output.
 482 The current name of the file to be output is appended to the filter command
 483 string before the command is executed by the shell.
 484 .TP
 485 .B h
 486 Inhibit archive heading and summmary information messages to stderr.
 487 .TP
 488 .B k
 489 For
 490 .B \-r
 491 continue processing the archive after encountering an error by attempting
 492 to locate the next valid entry.
 493 This is useful for archives stored on unreliable media.
 494 .TP
 495 .BI z " base"
 496 Specifies the delta base archive
 497 .I base
 498 that is assumed to be the result of a previous
 499 .B "pax \-w"
 500 command.
 501 For
 502 .B \-w
 503 the input files are compared with the files in
 504 .I base
 505 and file delta information is placed in the output archive
 506 using the delta algorithm.
 507 For
 508 .B \-r
 509 the delta information in the input archive is used to update the
 510 output files with respect to the files in
 511 .IR base .
 512 For
 513 .B \-rw
 514 the delta information in the archive on the standard input is used
 515 to generate an archive on the standard output whose entries are updated
 516 with respect to the files in
 517 .IR base .
 518 If
 519 .I base
 520 is
 521 .B \-
 522 or an empty file then the input files are simply compressed.
 523 .B "\-z -"
 524 must also be specified to produce a compressed archive for
 525 .BR \-rw .
 526 .TP
 527 .BI B " count"
 528 Sets the maximum archive part output character count.
 529 .I pax
 530 prompts for the next archive part file name.
 531 Valid only with
 532 .BR \-w .
 533 .TP
 534 .B C
 535 Archive entries smaller than
 536 .BI \-B " maxblocks"
 537 must be contained within a single part.
 538 Valid only with
 539 .BR \-B .
 540 .TP
 541 .B L
 542 Copy a logical view of the input files.
 543 Symbolic links are followed, causing the pointed to files to be copied
 544 rather than the symbolic link information.
 545 This is the default.
 546 .TP
 547 .BI M " message"
 548 Set the
 549 .I "end of medium"
 550 prompt to
 551 .IR message .
 552 This message is used to prompt interactively for the next tape
 553 reel or cartridge in cases where the tape runs out before
 554 all files have been copied.
 555 .I message
 556 may contain one
 557 .IR printf (3)
 558 style integer format specification that is replaced with the
 559 next part number.
 560 .TP
 561 .B P
 562 Copy a physical view of the input files.
 563 Causes symbolic link information to be copied as opposed to the
 564 default (logical view) action of following symbolic links
 565 and copying the pointed to files.
 566 .TP
 567 \fBR\fP \fIoption\fP[\fIvalue\fP][,\fIoption\fP[\fIvalue\fP]...]
 568 Set record oriented format options.
 569 Multiple options may be concatenated using
 570 .BR , .
 571 Some options may be fixed for some formats.
 572 The options are:
 573 .RS
 574 .PD 0
 575 .TP
 576 .B c
 577 Record data is subject to character set conversions.
 578 .TP
 579 .BI f format
 580 Set the output record format to
 581 .IR format .
 582 The supported record formats are:
 583 .RS
 584 .TP
 585 .B D
 586 Variable length with 4 byte record header.
 587 The record size default is 512.
 588 .TP
 589 .B F
 590 Fixed length with no record header.
 591 The record size default is 128.
 592 .TP
 593 .B S
 594 Spanned variable length with 4 byte record header.
 595 The record size default is 0 (no limit).
 596 .TP
 597 .B U
 598 Variable length with no record header.
 599 The output block size matches the size of each output record.
 600 The record size default is 512.
 601 .TP
 602 .B V
 603 Spanned variable length with binary 4 byte record header.
 604 The record size default is 0 (no limit).
 605 The
 606 .B D
 607 format is preferred.
 608 .PD
 609 .RE
 610 .TP
 611 .BI m pattern
 612 Only those files with input record format matching
 613 .I pattern
 614 are processed.
 615 .TP
 616 .B p
 617 Partial output blocks are padded to the full blocksize.
 618 .TP
 619 .BI s size
 620 Set the output record size to
 621 .IR size .
 622 .I size
 623 should divide the output blocking.
 624 .TP
 625 .BI v label
 626 Set the output volume label to
 627 .IR label .
 628 Some formats may truncate and/or case-convert
 629 .IR label .
 630 .PD
 631 .RE
 632 .TP
 633 .B S
 634 Similar to
 635 .B \-l
 636 except that symbolic links are created.
 637 .TP
 638 .BI U " id"
 639 Set file ownership to the default of the user named
 640 .IR id .
 641 Valid only for the super-user.
 642 .TP
 643 .B V
 644 Output a `.' as each file is encountered.
 645 This overrides the
 646 .B \-v
 647 option.
 648 .TP
 649 .B X
 650 Do not cross mount points when searching for files to output.
 651 .SH DIAGNOSTICS
 652 The number of files, blocks, and optionally the number of volumes and
 653 media parts are listed on the standard error.
 654 For
 655 .B \-v
 656 the input archive formats are also listed on the standard error.
 657 .SH EXAMPLES
 658 .TP
 659 .B "pax \-w \-t 1m ."
 660 Copies the contents of the current directory to tape drive 1, medium density.
 661 .TP
 662 .PD 0
 663 .BI mkdir "  newdir"
 664 .TP
 665 .BI cd "  olddir"
 666 .TP
 667 .BI "pax  \-rw  ." "  newdir"
 668 .PD
 669 Copies the
 670 .I olddir
 671 directory hierarchy to
 672 .IR newdir .
 673 .SH "SEE ALSO"
 674 ar(1), cpio(1), find(1), ksh(1), tar(1), tw(1), libdelta(3), cpio(5), tar(5)
 675 .SH BUGS
 676 Special privileges may be required to copy special files.
 677 .br
 678 Each archive format has a hard upper limit on member pathname sizes.
 679 .br
 680 Device, user-id and group-id numbers larger than 65535 cause additional
 681 header records to be output.
 682 These records are ignored by old versions of
 683 .IR cpio (1)
 684 and
 685 .IR tar (1).