sys/src/ape/cmd/pax/pax.1.man

   1 .\" $Id: pax.1,v 1.2 89/02/12 10:08:47 mark Exp $
   2 .TH PAX 1 "USENIX Association" ""
   3 .SH NAME
   4 pax \- portable archive exchange
   5 .SH SYNOPSIS
   6 .TP \w'\fBpax\fR\ 'u
   7 .B pax
   8 .RB [ \-cimopuvy ]
   9 .RI "[\fB\-f\fR" " archive" ]
  10 .RI "[\fB\-s\fR" " replstr" ]
  11 .RI "[\fB\-t\fR" " device" ]
  12 .RI [ pattern... ]
  13 .TP \w'\fBpax\ \-r\fR\ 'u
  14 .B "pax\ \-r"
  15 .RB [ \-cimnopuvy ]
  16 .RI "[\fB\-f\fR" " archive" ]
  17 .RI "[\fB\-s\fR" " replstr" ]
  18 .RI "[\fB\-t\fR" " device" ]
  19 .RI [ pattern... ]
  20 .TP \w'\fBpax\ \-w\fR\ 'u
  21 .B "pax\ \-w"
  22 .RB [ \-adimuvy ]
  23 .RI "[\fB\-b\fR" " blocking" ]
  24 .RI "[\fB\-f\fR" " archive" ]
  25 .RI "[\fB\-s\fR" " replstr" ]
  26 .RI "[\fB\-t\fR" " device" ]
  27 .RI "[\fB\-x\fR" " format" ]
  28 .RI [ pathname... ]
  29 .TP \w'\fBpax\ \-rw\fR\ 'u
  30 .B "pax\ \-rw"
  31 .RB [ \-ilmopuvy ]
  32 .RI "[\fB\-s\fR" " replstr" ]
  33 .RI [ pathname... ]
  34 directory
  35 .SH DESCRIPTION
  36 .I Pax
  37 reads and writes archive files which conform to the
  38 .B "Archive/Interchange File Format"
  39 specified in
  40 .IR "IEEE Std. 1003.1-1988" .
  41 .I Pax
  42 can also read, but not write, a number of other file formats
  43 in addition to those specified in the
  44 .B "Archive/Interchange File Format"
  45 description.
  46 Support for these traditional file formats, such as V7
  47 .I "tar"
  48 and System V binary
  49 .I "cpio"
  50 format archives,
  51 is provided for backward compatibility and to maximize portability.
  52 .PP
  53 .I Pax
  54 will also support traditional
  55 .I cpio
  56 and
  57 System V
  58 .I tar
  59 interfaces if invoked with the name
  60 "cpio" or "tar" respectively.
  61 See the
  62 .I cpio(1)
  63 or
  64 .I tar(1)
  65 manual pages for more details.
  66 .PP
  67 Combinations of the
  68 .B \-r
  69 and
  70 .B \-w
  71 command line arguments specify whether
  72 .I pax
  73 will read, write or list the contents of the specified archive,
  74 or move the specified files to another directory.
  75 .PP
  76 The command line arguments are:
  77 .TP .5i
  78 .B \-w
  79 writes the files and directories specified by
  80 .I pathname
  81 operands to the standard output together with the pathname and status
  82 information prescribed by the archive format used.
  83 A directory
  84 .I pathname
  85 operand refers to the files and (recursively) subdirectories of that
  86 directory.
  87 If no
  88 .I pathname
  89 operands are given, then the standard input is read to get a
  90 list of pathnames to copy, one pathname per line.
  91 In this case, only those pathnames appearing on the standard input are
  92 copied.
  93 .TP .5i
  94 .B \-r
  95 .I Pax
  96 reads an archive file from the standard input.
  97 Only files with names that match any of the
  98 .I pattern
  99 operands are selected for extraction.
 100 The selected files are conditionally created and copied relative to the
 101 current directory tree, subject to the options described below.
 102 By default, the owner and group of selected files will be that of the
 103 invoking process, and the permissions and modification times will be the
 104 sames as those in the archive.
 105 .RS .5i
 106 .PP
 107 The supported archive formats are automatically detected on input.
 108 The default output format is
 109 .IR ustar ,
 110 but may be overridden by the
 111 .B \-x
 112 .I format
 113 option described below.
 114 .RE
 115 .TP .5i
 116 .B \-rw
 117 .I Pax
 118 reads the files and directories named in the
 119 .I pathname
 120 operands and copies them to the destination
 121 .IR directory .
 122 A directory
 123 .I pathname
 124 operand refers to the files and (recursively) subdirectories of that
 125 directory.
 126 If no
 127 .I pathname
 128 operands are given, the standard input is read to get a list of pathnames
 129 to copy, one pathname per line.
 130 In this case, only those pathnames appearing on the standard input are
 131 copied.
 132 The directory named by the
 133 .I directory
 134 operand must exist and have the proper permissions before the copy can
 135 occur.
 136 .PP
 137 If neither the
 138 .BR \-r " or " \-w
 139 options are given, then
 140 .I pax
 141 will list the contents of the specified archive.
 142 In this mode,
 143 .I pax
 144 lists normal files one per line, hard link pathnames as
 145 .sp
 146 .RS 1i
 147 .IR pathname " == " linkname
 148 .RE
 149 .sp
 150 and symbolic link pathnames (if supported by the implementation) as
 151 .sp
 152 .RS 1i
 153 .IR pathname " -> " linkname
 154 .RE
 155 .sp
 156 where
 157 .I pathname
 158 is the name of the file being extracted, and
 159 .I linkname
 160 is the name of a file which appeared earlier in the archive.
 161 .PP
 162 If the
 163 .B \-v
 164 option is specified, then
 165 .I pax
 166 list normal pathnames in the same format used by the
 167 .I ls
 168 utility with the
 169 .B \-l
 170 option.
 171 Hard links are shown as
 172 .sp
 173 .RS 1i
 174 .IR "<ls -l listing>" " == " linkname
 175 .RE
 176 .sp
 177 and symbolic links (if supported) are shown as
 178 .sp
 179 .RS 1i
 180 .IR "<ls -l listing>" " -> " linkname
 181 .RE
 182 .sp
 183 .PP
 184 .I Pax
 185 is capable of reading and writing archives which span multiple physical
 186 volumes.
 187 Upon detecting an end of medium on an archive which is not yet completed,
 188 .I pax
 189 will prompt the user for the next volume of the archive and will allow the
 190 user to specify the location of the next volume.
 191 .SS Options
 192 The following options are available:
 193 .TP 1i
 194 .B \-a
 195 The files specified by
 196 .I pathname
 197 are appended to the specified archive.
 198 .TP 1i
 199 .BI \-b " blocking"
 200 Block the output at
 201 .I blocking
 202 bytes per write to the archive file.
 203 A
 204 .B k
 205 suffix multiplies
 206 .I blocking
 207 by 1024, a
 208 .B b
 209 suffix multiplies
 210 .I blocking
 211 by 512 and a
 212 .B m
 213 suffix multiplies
 214 .I blocking
 215 by 1048576 (1 megabyte).
 216 For machines with 16-bit int's (VAXen, XENIX-286, etc.),
 217 the maximum buffer size is 32k-1.
 218 If not specified,
 219 .I blocking
 220 is automatically determined on input and is ignored for
 221 .B \-rw.
 222 .TP 1i
 223 .B \-c
 224 Complement the match sense of the
 225 .I pattern
 226 operands.
 227 .TP 1i
 228 .B \-d
 229 Intermediate directories not explicitly listed in the archive are not
 230 created.
 231 This option is ignored unless
 232 the
 233 .B \-r
 234 option is specified.
 235 .TP 1i
 236 .BI \-f " archive"
 237 The
 238 .I archive
 239 option specifies the pathname of the input or output archive,
 240 overriding the default of standard input for
 241 .B \-r
 242 or standard output for
 243 .BR \-w .
 244 .TP 1i
 245 .B \-i
 246 Interactively rename files.
 247 Substitutions specified by
 248 .B \-s
 249 options (described below)
 250 are performed before requesting the new file name from the user.
 251 A file is skipped if an empty line is entered and
 252 .I pax
 253 exits with an exit status of 0 if
 254 .B EOF
 255 is encountered.
 256 .TP 1i
 257 .B \-l
 258 Files are linked rather than copied when possible.
 259 .TP 1i
 260 .B \-m
 261 File modification times are not retained.
 262 .TP 1i
 263 .B \-n
 264 When
 265 .B \-r
 266 is specified, but
 267 .B \-w
 268 is not, the
 269 .I pattern
 270 arguments are treated as ordinary file names.
 271 Only the first occurrence of each of these files in the input archive
 272 is read.
 273 The
 274 .B pax
 275 utility exits with a zero exit status after all files in the list have been
 276 read.
 277 If one or more files in the list is not found,
 278 .B pax
 279 writes a diagnostic to standard error for each of the files and exits with
 280 a non-zero exit status.
 281 the file names are compared before any of the
 282 .BR \-i ,
 283 .BR \-s ,
 284 or
 285 .B \-y
 286 options are applied.
 287 .TP 1i
 288 .B \-o
 289 Restore file ownership as specified in the archive.
 290 The invoking process must have appropriate privileges to accomplish this.
 291 .TP 1i
 292 .B \-p
 293 Preserve the access time of the input files after they have been copied.
 294 .TP 1i
 295 .BI \-s " replstr"
 296 File names are modified according to the substitution expression using the
 297 syntax of
 298 .I "ed(1)"
 299 as shown:
 300 .sp
 301 .RS 2i
 302 -s /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR
 303 .RE
 304 .RS 1i
 305 .PP
 306 Any non null character may be used as a delimiter (a / is used here as an
 307 example).
 308 Multiple
 309 .B \-s
 310 expressions may be specified; the expressions are applied in the order
 311 specified terminating with the first successful substitution.
 312 The optional trailing
 313 .B p
 314 causes successful mappings to be listed on standard error.
 315 The optional trailing
 316 .B g
 317 causes the
 318 .I old
 319 expression to be replaced each time it occurs in the source string.
 320 Files that substitute to an empty string are ignored both on input and
 321 output.
 322 .RE
 323 .TP 1i
 324 .BI \-t " device"
 325 The
 326 .I device
 327 option argument is an implementation-defined identifier that names the input
 328 or output archive device, overriding the default of standard input for
 329 .B \-r
 330 and standard output for
 331 .BR \-w .
 332 .TP 1i
 333 .B \-u
 334 Copy each file only if it is newer than a pre-existing file with the same
 335 name.
 336 This implies
 337 .BR \-a .
 338 .TP 1i
 339 .B \-v
 340 List file names as they are encountered.
 341 Produces a verbose table of contents listing on the standard output when both
 342 .B \-r
 343 and
 344 .B \-w
 345 are omitted,
 346 otherwise the file names are printed to standard error as they are
 347 encountered in the archive.
 348 .TP 1i
 349 .BI \-x " format"
 350 Specifies the output archive
 351 .IR format .
 352 The input format, which must be one of the following, is automatically
 353 determined when the
 354 .B \-r
 355 option is used.
 356 The supported formats are:
 357 .RS 1i
 358 .TP 0.75i
 359 .I cpio
 360 The extended
 361 .I CPIO
 362 interchange format specified in
 363 .B "Extended CPIO Format" in
 364 .I "IEEE Std. 1003.1-1988."
 365 .TP 0.75i
 366 .I ustar
 367 The extended
 368 .I TAR
 369 interchange format specified in
 370 .B "Extended TAR Format" in
 371 .I "IEEE Std. 1003.1-1988."
 372 This is the default archive format.
 373 .RE
 374 .TP 1i
 375 .B \-y
 376 Interactively prompt for the disposition of each file.
 377 Substitutions specified by
 378 .B \-s
 379 options (described above)
 380 are performed before prompting the user for disposition.
 381 .B EOF
 382 or an input line starting with the character
 383 .B q
 384 caused
 385 .I pax
 386 to exit.
 387 Otherwise, an input line starting with anything other than
 388 .B y
 389 causes the file to be ignored.
 390 This option cannot be used in conjunction with the
 391 .B \-i
 392 option.
 393 .PP
 394 Only the last of multiple
 395 .B \-f
 396 or
 397 .B \-t
 398 options take effect.
 399 .PP
 400 When writing to an archive, the
 401 standard input is used as a list of pathnames if no
 402 .I pathname
 403 operands are specified.
 404 The format is one pathname per line.
 405 Otherwise, the standard input is the archive file,
 406 which is formatted according to one of the specifications in
 407 .B "Archive/Interchange File format"
 408 in
 409 .IR "IEEE Std. 1003.1-1988" ,
 410 or some other implementation-defined format.
 411 .PP
 412 The user ID and group ID of the process, together with the appropriate
 413 privileges, affect the ability of
 414 .I pax
 415 to restore ownership and permissions attributes of the archived files.
 416 (See
 417 .I "format-reading utility"
 418 in
 419 .B "Archive/Interchange File Format"
 420 in
 421 .IR "IEEE Std. 1003.1-1988" ".)"
 422 .PP
 423 The options
 424 .BR \-a ,
 425 .BR \-c ,
 426 .BR \-d ,
 427 .BR \-i ,
 428 .BR \-l ,
 429 .BR \-p ,
 430 .BR \-t ,
 431 .BR \-u ,
 432 and
 433 .BR \-y
 434 are provided for functional compatibility with the historical
 435 .I cpio
 436 and
 437 .I tar
 438 utilities.
 439 The option defaults were chosen based on the most common usage of these
 440 options, therefore, some of the options have meanings different than
 441 those of the historical commands.
 442 .SS Operands
 443 The following operands are available:
 444 .TP 1i
 445 .I directory
 446 The destination directory pathname for copies when both the
 447 .B \-r
 448 and
 449 .B \-w
 450 options are specified.
 451 The directory must exist and be writable before the copy or and error
 452 results.
 453 .TP 1i
 454 .I pathname
 455 A file whose contents are used instead of the files named on the standard
 456 input.
 457 When a directory is named, all of its files and (recursively)
 458 subdirectories
 459 are copied as well.
 460 .TP 1i
 461 .IR pattern
 462 A
 463 .I pattern
 464 is given in the standard shell pattern matching notation.
 465 The default if no
 466 .I pattern
 467 is  specified is
 468 .BR * \,
 469 which selects all files.
 470 .SH EXAMPLES
 471 The following command
 472 .sp
 473 .RS 1i
 474 pax \-w \-f /dev/rmt0 \.
 475 .RE
 476 .sp
 477 copies the contents of the current directory to tape drive 0.
 478 .PP
 479 The commands
 480 .sp
 481 .RS 1i
 482 .RI mkdir " newdir"
 483 .br
 484 .RI cd " olddir"
 485 .br
 486 .RI "pax -rw . " newdir
 487 .RE
 488 .sp
 489 copies the contents of
 490 .I olddir
 491 to
 492 .I newdir .
 493 .PP
 494 The command
 495 .sp
 496 .RS 1i
 497 pax \-r \-s ',//*usr//*,,' -f pax.out
 498 .RE
 499 .sp
 500 reads the archive
 501 .B pax.out
 502 with all files rooted in "/usr" in the archive extracted
 503 relative to the current directory.
 504 .SH FILES
 505 .TP 1i
 506 /dev/tty
 507 used to prompt the user for information when the
 508 .BR \-i " or " \-y
 509 options are specified.
 510 .SH "SEE ALSO"
 511 cpio(1), find(1), tar(1), cpio(5), tar(5)
 512 .SH DIAGNOSTICS
 513 .I Pax
 514 will terminate immediately, without processing any
 515 additional files on the command line or in the archive.
 516 .SH "EXIT CODES"
 517 .I Pax
 518 will exit with one of the following values:
 519 .IP 0 .5i
 520 All files in the archive were processed successfully.
 521 .IP ">0" .5i
 522 .I Pax
 523 aborted due to errors encountered during operation.
 524 .SH BUGS
 525 Special permissions may be required to copy or extract special files.
 526 .PP
 527 Device, user ID, and group ID numbers larger than 65535 cause additional
 528 header records to be output.
 529 These records are ignored by some historical version of
 530 .I "cpio(1)"
 531 and
 532 .IR "tar(1)" .
 533 .PP
 534 The archive formats described in
 535 .B "Archive/Interchange File Format"
 536 have certain restrictions that have
 537 been carried over from historical usage.
 538 For example, there are restrictions on the length of pathnames stored in
 539 the archive.
 540 .PP
 541 When getting an "ls -l" style listing on
 542 .I tar
 543 format archives, link counts are listed as zero since the
 544 .I ustar
 545 archive format does not keep link count information.
 546 .PP
 547 On 16 bit architectures, the largest buffer size is 32k-1.
 548 This is due, in part, to using integers in the buffer allocation schemes,
 549 however, on many of these machines, it is not possible to allocate blocks
 550 of memory larger than 32k.
 551 .SH COPYRIGHT
 552 Copyright (c) 1989 Mark H. Colburn.
 553 .br
 554 All rights reserved.
 555 .PP
 556 Redistribution and use in source and binary forms are permitted
 557 provided that the above copyright notice is duplicated in all such
 558 forms and that any documentation, advertising materials, and other
 559 materials related to such distribution and use acknowledge that the
 560 software was developed by Mark H. Colburn and sponsored by The
 561 USENIX Association.
 562 .PP
 563 THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
 564 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 565 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 566 .SH AUTHOR
 567 Mark H. Colburn
 568 .br
 569 Minnetech Consulting, Inc.
 570 .br
 571 117 Mackubin Street, Suite 1
 572 .br
 573 St. Paul, MN 55102
 574 .br
 575 mark@jhereg.MN.ORG
 576 .sp 2
 577 Sponsored by
 578 .B "The USENIX Association"
 579 for public distribution.