1.\" $NetBSD: pax.1,v 1.36 2002/10/16 21:49:08 christos Exp $ 2.\" 3.\" Copyright (c) 1992 Keith Muller. 4.\" Copyright (c) 1992, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Keith Muller of the University of California, San Diego. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)pax.1 8.4 (Berkeley) 4/18/94 39.\" 40.Dd April 21, 2002 41.Dt PAX 1 42.Os 43.Sh NAME 44.Nm pax 45.Nd read and write file archives and copy directory hierarchies 46.Sh SYNOPSIS 47.Nm "" 48.Op Fl cdnvzO 49.Bk -words 50.Op Fl E Ar limit 51.Ek 52.Bk -words 53.Op Fl f Ar archive 54.Ek 55.Bk -words 56.Op Fl N Ar dbdir 57.Ek 58.Bk -words 59.Op Fl s Ar replstr 60.Ar ...\& 61.Ek 62.Bk -words 63.Op Fl U Ar user 64.Ar ...\& 65.Ek 66.Bk -words 67.Op Fl G Ar group 68.Ar ...\& 69.Ek 70.Bk -words 71.Oo 72.Fl T 73.Op Ar from_date 74.Sm off 75.Oo , Ar to_date Oc 76.Sm on 77.Oc 78.Ar ...\& 79.Ek 80.Op Ar pattern ...\& 81.Nm "" 82.Fl r 83.Op Fl cdiknuvzADOYZ 84.Bk -words 85.Op Fl E Ar limit 86.Ek 87.Bk -words 88.Op Fl f Ar archive 89.Ek 90.Bk -words 91.Op Fl N Ar dbdir 92.Ek 93.Bk -words 94.Op Fl o Ar options 95.Ar ...\& 96.Ek 97.Bk -words 98.Op Fl p Ar string 99.Ar ...\& 100.Ek 101.Bk -words 102.Op Fl s Ar replstr 103.Ar ...\& 104.Ek 105.Bk -words 106.Op Fl U Ar user 107.Ar ...\& 108.Ek 109.Bk -words 110.Op Fl G Ar group 111.Ar ...\& 112.Ek 113.Bk -words 114.Oo 115.Fl T 116.Op Ar from_date 117.Sm off 118.Oo , Ar to_date Oc 119.Sm on 120.Oc 121.Ar ...\& 122.Ek 123.Op Ar pattern ...\& 124.Nm "" 125.Fl w 126.Op Fl dituvzAHLMOPX 127.Bk -words 128.Op Fl b Ar blocksize 129.Ek 130.Oo 131.Op Fl a 132.Op Fl f Ar archive 133.Oc 134.Bk -words 135.Op Fl x Ar format 136.Ek 137.Bk -words 138.Op Fl B Ar bytes 139.Ek 140.Bk -words 141.Op Fl N Ar dbdir 142.Ek 143.Bk -words 144.Op Fl o Ar options 145.Ar ...\& 146.Ek 147.Bk -words 148.Op Fl s Ar replstr 149.Ar ...\& 150.Ek 151.Bk -words 152.Op Fl U Ar user 153.Ar ...\& 154.Ek 155.Bk -words 156.Op Fl G Ar group 157.Ar ...\& 158.Ek 159.Bk -words 160.Oo 161.Fl T 162.Op Ar from_date 163.Sm off 164.Oo , Ar to_date Oc 165.Oo /[ Cm c ] [ Cm m ] Oc 166.Sm on 167.Oc 168.Ar ...\& 169.Ek 170.Op Ar file ...\& 171.Nm "" 172.Fl r 173.Fl w 174.Op Fl diklntuvzADHLMOPXYZ 175.Bk -words 176.Op Fl N Ar dbdir 177.Ek 178.Bk -words 179.Op Fl p Ar string 180.Ar ...\& 181.Ek 182.Bk -words 183.Op Fl s Ar replstr 184.Ar ...\& 185.Ek 186.Bk -words 187.Op Fl U Ar user 188.Ar ...\& 189.Ek 190.Bk -words 191.Op Fl G Ar group 192.Ar ...\& 193.Ek 194.Bk -words 195.Oo 196.Fl T 197.Op Ar from_date 198.Sm off 199.Oo , Ar to_date Oc 200.Oo /[ Cm c ] [ Cm m ] Oc 201.Sm on 202.Oc 203.Ar ...\& 204.Ek 205.Bk -words 206.Op Ar file ...\& 207.Ek 208.Ar directory 209.Sh DESCRIPTION 210.Nm 211will read, write, and list the members of an archive file, 212and will copy directory hierarchies. 213If the archive file is of the form: 214.Ar [[user@]host:]file 215then the archive will be processed using 216.Xr rmt 8 . 217.Pp 218.Nm 219operation is independent of the specific archive format, 220and supports a wide variety of different archive formats. 221A list of supported archive formats can be found under the description of the 222.Fl x 223option. 224.Pp 225The presence of the 226.Fl r 227and the 228.Fl w 229options specifies which of the following functional modes 230.Nm 231will operate under: 232.Em list , read , write , 233and 234.Em copy . 235.Bl -tag -width 6n 236.It Aq none 237.Em List . 238.Nm 239will write to 240.Dv standard output 241a table of contents of the members of the archive file read from 242.Dv standard input , 243whose pathnames match the specified 244.Ar patterns . 245The table of contents contains one filename per line 246and is written using single line buffering. 247.It Fl r 248.Em Read . 249.Nm 250extracts the members of the archive file read from the 251.Dv standard input , 252with pathnames matching the specified 253.Ar patterns . 254The archive format and blocking is automatically determined on input. 255When an extracted file is a directory, the entire file hierarchy 256rooted at that directory is extracted. 257All extracted files are created relative to the current file hierarchy. 258The setting of ownership, access and modification times, and file mode of 259the extracted files are discussed in more detail under the 260.Fl p 261option. 262.It Fl w 263.Em Write . 264.Nm 265writes an archive containing the 266.Ar file 267operands to 268.Dv standard output 269using the specified archive format. 270When no 271.Ar file 272operands are specified, a list of files to copy with one per line is read from 273.Dv standard input . 274When a 275.Ar file 276operand is also a directory, the entire file hierarchy rooted 277at that directory will be included. 278.It Fl r Fl w 279.Em Copy . 280.Nm 281copies the 282.Ar file 283operands to the destination 284.Ar directory . 285When no 286.Ar file 287operands are specified, a list of files to copy with one per line is read from 288the 289.Dv standard input . 290When a 291.Ar file 292operand is also a directory the entire file 293hierarchy rooted at that directory will be included. 294The effect of the 295.Em copy 296is as if the copied files were written to an archive file and then 297subsequently extracted, except that there may be hard links between 298the original and the copied files (see the 299.Fl l 300option below). 301.Pp 302.Em Warning : 303The destination 304.Ar directory 305must not be one of the 306.Ar file 307operands or a member of a file hierarchy rooted at one of the 308.Ar file 309operands. 310The result of a 311.Em copy 312under these conditions is unpredictable. 313.El 314.Pp 315While processing a damaged archive during a 316.Em read 317or 318.Em list 319operation, 320.Nm 321will attempt to recover from media defects and will search through the archive 322to locate and process the largest number of archive members possible (see the 323.Fl E 324option for more details on error handling). 325.Sh OPERANDS 326The 327.Ar directory 328operand specifies a destination directory pathname. 329If the 330.Ar directory 331operand does not exist, or it is not writable by the user, 332or it is not of type directory, 333.Nm 334will exit with a non-zero exit status. 335.Pp 336The 337.Ar pattern 338operand is used to select one or more pathnames of archive members. 339Archive members are selected using the pattern matching notation described 340by 341.Xr fnmatch 3 . 342When the 343.Ar pattern 344operand is not supplied, all members of the archive will be selected. 345When a 346.Ar pattern 347matches a directory, the entire file hierarchy rooted at that directory will 348be selected. 349When a 350.Ar pattern 351operand does not select at least one archive member, 352.Nm 353will write these 354.Ar pattern 355operands in a diagnostic message to 356.Dv standard error 357and then exit with a non-zero exit status. 358.Pp 359The 360.Ar file 361operand specifies the pathname of a file to be copied or archived. 362When a 363.Ar file 364operand does not select at least one archive member, 365.Nm 366will write these 367.Ar file 368operand pathnames in a diagnostic message to 369.Dv standard error 370and then exit with a non-zero exit status. 371.Sh OPTIONS 372The following options are supported: 373.Bl -tag -width 4n 374.It Fl r 375Read an archive file from 376.Dv standard input 377and extract the specified 378.Ar files . 379If any intermediate directories are needed in order to extract an archive 380member, these directories will be created as if 381.Xr mkdir 2 382was called with the bitwise inclusive 383.Dv OR 384of 385.Dv S_IRWXU , S_IRWXG , 386and 387.Dv S_IRWXO 388as the mode argument. 389When the selected archive format supports the specification of linked 390files and these files cannot be linked while the archive is being extracted, 391.Nm 392will write a diagnostic message to 393.Dv standard error 394and exit with a non-zero exit status at the completion of operation. 395.It Fl w 396Write files to the 397.Dv standard output 398in the specified archive format. 399When no 400.Ar file 401operands are specified, 402.Dv standard input 403is read for a list of pathnames with one per line without any leading or 404trailing 405.Aq blanks . 406.It Fl a 407Append 408.Ar files 409to the end of an archive that was previously written. 410If an archive format is not specified with a 411.Fl x 412option, the format currently being used in the archive will be selected. 413Any attempt to append to an archive in a format different from the 414format already used in the archive will cause 415.Nm 416to exit immediately 417with a non-zero exit status. 418The blocking size used in the archive volume where writing starts 419will continue to be used for the remainder of that archive volume. 420.Pp 421.Em Warning : 422Many storage devices are not able to support the operations necessary 423to perform an append operation. 424Any attempt to append to an archive stored on such a device may damage the 425archive or have other unpredictable results. 426Tape drives in particular are more likely to not support an append operation. 427An archive stored in a regular file system file or on a disk device will 428usually support an append operation. 429.It Fl b Ar blocksize 430When 431.Em writing 432an archive, 433block the output at a positive decimal integer number of 434bytes per write to the archive file. 435The 436.Ar blocksize 437must be a multiple of 512 bytes with a maximum of 32256 bytes. 438A 439.Ar blocksize 440can end with 441.Li k 442or 443.Li b 444to specify multiplication by 1024 (1K) or 512, respectively. 445A pair of 446.Ar blocksizes 447can be separated by 448.Li x 449to indicate a product. 450A specific archive device may impose additional restrictions on the size 451of blocking it will support. 452When blocking is not specified, the default 453.Ar blocksize 454is dependent on the specific archive format being used (see the 455.Fl x 456option). 457.It Fl c 458Match all file or archive members 459.Em except 460those specified by the 461.Ar pattern 462and 463.Ar file 464operands. 465.It Fl d 466Cause files of type directory being copied or archived, or archive members of 467type directory being extracted, to match only the directory file or archive 468member and not the file hierarchy rooted at the directory. 469.It Fl f Ar archive 470Specify 471.Ar archive 472as the pathname of the input or output archive, overriding the default 473.Dv standard input 474(for 475.Em list 476and 477.Em read ) 478or 479.Dv standard output 480(for 481.Em write ) . 482A single archive may span multiple files and different archive devices. 483When required, 484.Nm 485will prompt for the pathname of the file or device of the next volume in the 486archive. 487.It Fl i 488Interactively rename files or archive members. 489For each archive member matching a 490.Ar pattern 491operand or each file matching a 492.Ar file 493operand, 494.Nm 495will prompt to 496.Pa /dev/tty 497giving the name of the file, its file mode and its modification time. 498.Nm 499will then read a line from 500.Pa /dev/tty . 501If this line is blank, the file or archive member is skipped. 502If this line consists of a single period, the 503file or archive member is processed with no modification to its name. 504Otherwise, its name is replaced with the contents of the line. 505.Nm 506will immediately exit with a non-zero exit status if 507.Aq Dv EOF 508is encountered when reading a response or if 509.Pa /dev/tty 510cannot be opened for reading and writing. 511.It Fl k 512Do not overwrite existing files. 513.It Fl l 514Link files. 515(The letter ell). 516In the 517.Em copy 518mode 519.Fl ( r 520.Fl w ) , 521hard links are made between the source and destination file hierarchies 522whenever possible. 523.It Fl n 524Select the first archive member that matches each 525.Ar pattern 526operand. 527No more than one archive member is matched for each 528.Ar pattern . 529When members of type directory are matched, the file hierarchy rooted at that 530directory is also matched (unless 531.Fl d 532is also specified). 533.It Fl o Ar options 534Information to modify the algorithm for extracting or writing archive files 535which is specific to the archive format specified by 536.Fl x . 537In general, 538.Ar options 539take the form: 540.Cm name=value 541.It Fl p Ar string 542Specify one or more file characteristic options (privileges). 543The 544.Ar string 545option-argument is a string specifying file characteristics to be retained or 546discarded on extraction. 547The string consists of the specification characters 548.Cm a , e , f , 549.Cm m , o , 550and 551.Cm p . 552Multiple characteristics can be concatenated within the same string 553and multiple 554.Fl p 555options can be specified. 556The meaning of the specification characters are as follows: 557.Bl -tag -width 2n 558.It Cm a 559Do not preserve file access times. 560By default, file access times are preserved whenever possible. 561.It Cm e 562.Sq Preserve everything , 563the user ID, group ID, file mode bits, 564file access time, and file modification time. 565This is intended to be used by 566.Em root , 567someone with all the appropriate privileges, in order to preserve all 568aspects of the files as they are recorded in the archive. 569The 570.Cm e 571flag is the sum of the 572.Cm o 573and 574.Cm p 575flags. 576.\" .It Cm f 577.\" Do not preserve file flags. 578.\" By default, file flags are preserved whenever possible. 579.It Cm m 580Do not preserve file modification times. 581By default, file modification times are preserved whenever possible. 582.It Cm o 583Preserve the user ID and group ID. 584.It Cm p 585.Sq Preserve 586the file mode bits. 587This intended to be used by a 588.Em user 589with regular privileges who wants to preserve all aspects of the file other 590than the ownership. 591The file times are preserved by default, but two other flags are offered to 592disable this and use the time of extraction instead. 593.El 594.Pp 595In the preceding list, 596.Sq preserve 597indicates that an attribute stored in the archive is given to the 598extracted file, subject to the permissions of the invoking 599process. 600Otherwise the attribute of the extracted file is determined as 601part of the normal file creation action. 602If neither the 603.Cm e 604nor the 605.Cm o 606specification character is specified, or the user ID and group ID are not 607preserved for any reason, 608.Nm 609will not set the 610.Dv S_ISUID 611.Em ( setuid ) 612and 613.Dv S_ISGID 614.Em ( setgid ) 615bits of the file mode. 616If the preservation of any of these items fails for any reason, 617.Nm 618will write a diagnostic message to 619.Dv standard error . 620Failure to preserve these items will affect the final exit status, 621but will not cause the extracted file to be deleted. 622If the file characteristic letters in any of the string option-arguments are 623duplicated or conflict with each other, the one(s) given last will take 624precedence. 625For example, if 626.Dl Fl p Ar eme 627is specified, file modification times are still preserved. 628.It Fl s Ar replstr 629Modify the file or archive member names specified by the 630.Ar pattern 631or 632.Ar file 633operands according to the substitution expression 634.Ar replstr , 635using the syntax of the 636.Xr ed 1 637utility regular expressions. 638The format of these regular expressions are: 639.Dl /old/new/[gp] 640As in 641.Xr ed 1 , 642.Cm old 643is a basic regular expression and 644.Cm new 645can contain an ampersand (\*[Am]), \\n (where n is a digit) back-references, 646or subexpression matching. 647The 648.Cm old 649string may also contain 650.Aq Dv newline 651characters. 652Any non-null character can be used as a delimiter (/ is shown here). 653Multiple 654.Fl s 655expressions can be specified. 656The expressions are applied in the order they are specified on the 657command line, terminating with the first successful substitution. 658The optional trailing 659.Cm g 660continues to apply the substitution expression to the pathname substring 661which starts with the first character following the end of the last successful 662substitution. 663The first unsuccessful substitution stops the operation of the 664.Cm g 665option. 666The optional trailing 667.Cm p 668will cause the final result of a successful substitution to be written to 669.Dv standard error 670in the following format: 671.Dl Ao "original pathname" Ac \*[Gt]\*[Gt] Ao "new pathname" Ac 672File or archive member names that substitute to the empty string 673are not selected and will be skipped. 674.It Fl t 675Reset the access times of any file or directory read or accessed by 676.Nm 677to be the same as they were before being read or accessed by 678.Nm "" , 679if the user has the appropriate permissions required by 680.Xr utime 3 . 681.It Fl u 682Ignore files that are older (having a less recent file modification time) 683than a pre-existing file or archive member with the same name. 684During 685.Em read , 686an archive member with the same name as a file in the file system will be 687extracted if the archive member is newer than the file. 688During 689.Em write , 690a file system member with the same name as an archive member will be 691written to the archive if it is newer than the archive member. 692During 693.Em copy , 694the file in the destination hierarchy is replaced by the file in the source 695hierarchy or by a link to the file in the source hierarchy if the file in 696the source hierarchy is newer. 697.It Fl v 698During a 699.Em list 700operation, produce a verbose table of contents using the format of the 701.Xr ls 1 702utility with the 703.Fl l 704option. 705For pathnames representing a hard link to a previous member of the archive, 706the output has the format: 707.Dl Ao "ls -l listing" Ac == Ao "link name" Ac 708For pathnames representing a symbolic link, the output has the format: 709.Dl Ao "ls -l listing" Ac =\*[Gt] Ao "link name" Ac 710Where 711.Aq "ls -l listing" 712is the output format specified by the 713.Xr ls 1 714utility when used with the 715.Fl l 716option. 717Otherwise for all the other operational modes 718.Em ( read , write , 719and 720.Em copy ) , 721pathnames are written and flushed to 722.Dv standard error 723without a trailing 724.Aq Dv newline 725as soon as processing begins on that file or 726archive member. 727The trailing 728.Aq Dv newline , 729is not buffered, and is written only after the file has been read or written. 730.It Fl x Ar format 731Specify the output archive format, with the default format being 732.Ar ustar . 733.Nm 734currently supports the following formats: 735.Bl -tag -width "sv4cpio" 736.It Ar cpio 737The extended cpio interchange format specified in the 738.St -p1003.2 739standard. 740The default blocksize for this format is 5120 bytes. 741Inode and device information about a file (used for detecting file hard links 742by this format) which may be truncated by this format is detected by 743.Nm 744and is repaired. 745.It Ar bcpio 746The old binary cpio format. 747The default blocksize for this format is 5120 bytes. 748This format is not very portable and should not be used when other formats 749are available. 750Inode and device information about a file (used for detecting file hard links 751by this format) which may be truncated by this format is detected by 752.Nm 753and is repaired. 754.It Ar sv4cpio 755The 756.At V.4 757cpio. 758The default blocksize for this format is 5120 bytes. 759Inode and device information about a file (used for detecting file hard links 760by this format) which may be truncated by this format is detected by 761.Nm 762and is repaired. 763.It Ar sv4crc 764The 765.At V.4 766cpio with file crc checksums. 767The default blocksize for this format is 5120 bytes. 768Inode and device information about a file (used for detecting file hard links 769by this format) which may be truncated by this format is detected by 770.Nm 771and is repaired. 772.It Ar tar 773The old 774.Bx 775tar format as found in 776.Bx 4.3 . 777The default blocksize for this format is 10240 bytes. 778Pathnames stored by this format must be 100 characters or less in length. 779Only 780.Em regular 781files, 782.Em hard links , soft links , 783and 784.Em directories 785will be archived (other file system types are not supported). 786For backwards compatibility with even older tar formats, a 787.Fl o 788option can be used when writing an archive to omit the storage of directories. 789This option takes the form: 790.Dl Fl o Cm write_opt=nodir 791.It Ar ustar 792The extended tar interchange format specified in the 793.St -p1003.2 794standard. 795The default blocksize for this format is 10240 bytes. 796Pathnames stored by this format must be 250 characters or less in length. 797.El 798.Pp 799.Nm 800will detect and report any file that it is unable to store or extract 801as the result of any specific archive format restrictions. 802The individual archive formats may impose additional restrictions on use. 803Typical archive format restrictions include (but are not limited to): 804file pathname length, file size, link pathname length and the type of the file. 805.It Fl z 806Use 807.Xr gzip 1 808compression, when reading or writing archive files. 809.It Fl A 810Do not strip leading `/'s from file names. 811.It Fl B Ar bytes 812Limit the number of bytes written to a single archive volume to 813.Ar bytes . 814The 815.Ar bytes 816limit can end with 817.Li m , 818.Li k , 819or 820.Li b 821to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively. 822A pair of 823.Ar bytes 824limits can be separated by 825.Li x 826to indicate a product. 827.Pp 828.Em Warning : 829Only use this option when writing an archive to a device which supports 830an end of file read condition based on last (or largest) write offset 831(such as a regular file or a tape drive). 832The use of this option with a floppy or hard disk is not recommended. 833.It Fl D 834This option is the same as the 835.Fl u 836option, except that the file inode change time is checked instead of the 837file modification time. 838The file inode change time can be used to select files whose inode information 839(e.g. uid, gid, etc.) is newer than a copy of the file in the destination 840.Ar directory . 841.It Fl E Ar limit 842Limit the number of consecutive read faults while trying to read a flawed 843archives to 844.Ar limit . 845With a positive 846.Ar limit , 847.Nm 848will attempt to recover from an archive read error and will 849continue processing starting with the next file stored in the archive. 850A 851.Ar limit 852of 0 will cause 853.Nm 854to stop operation after the first read error is detected on an archive volume. 855A 856.Ar limit 857of 858.Li NONE 859will cause 860.Nm 861to attempt to recover from read errors forever. 862The default 863.Ar limit 864is a small positive number of retries. 865.Pp 866.Em Warning : 867Using this option with 868.Li NONE 869should be used with extreme caution as 870.Nm 871may get stuck in an infinite loop on a very badly flawed archive. 872.It Fl G Ar group 873Select a file based on its 874.Ar group 875name, or when starting with a 876.Cm # , 877a numeric gid. 878A '\\' can be used to escape the 879.Cm # . 880Multiple 881.Fl G 882options may be supplied and checking stops with the first match. 883.It Fl H 884Follow only command line symbolic links while performing a physical file 885system traversal. 886.It Fl L 887Follow all symbolic links to perform a logical file system traversal. 888.It Fl M 889During a 890.Em write 891or 892.Em copy 893operation, treat the list of files on 894.Dv standard input 895as an 896.Xr mtree 8 897.Sq specfile 898specification, and write or copy only those items in the specfile. 899.Pp 900If the file exists in the underlying file system, its permissions and 901modification time will be used unless specifically overridden by the specfile. 902An error will be raised if the type of entry in the specfile conflicts 903with that of an existing file. 904A directory entry that is marked 905.Sq Sy optional 906will not be copied (even though its contents will be). 907.Pp 908Otherwise, the entry will be 909.Sq faked-up , 910and it is necessary to specify at least the following parameters 911in the specfile: 912.Sy type , 913.Sy mode , 914.Sy gname 915or 916.Sy gid , 917and 918.Sy uname 919or 920.Sy uid , 921.Sy device 922(in the case of block or character devices), and 923.Sy link 924(in the case of symbolic links). 925If 926.Sy time 927isn't provided, the current time will be used. 928A 929.Sq faked-up 930entry that is marked 931.Sq Sy optional 932will not be copied. 933.It Fl N Ar dbdir 934Except for lookups for the 935.Fl G 936and 937.Fl U 938options, 939use the user database text file 940.Pa master.passwd 941and group database text file 942.Pa group 943from 944.Ar dbdir , 945rather than using the results from the system's 946.Xr getpwnam 3 947and 948.Xr getgrnam 3 949(and related) library calls. 950.It Fl O 951Force the archive to be one volume. 952If a volume ends prematurely, 953.Nm 954will not prompt for a new volume. 955This option can be useful for 956automated tasks where error recovery cannot be performed by a human. 957.It Fl P 958Do not follow symbolic links, perform a physical file system traversal. 959This is the default mode. 960.It Fl T Ar [from_date][,to_date][/[c][m]] 961Allow files to be selected based on a file modification or inode change 962time falling within a specified time range of 963.Ar from_date 964to 965.Ar to_date 966(the dates are inclusive). 967If only a 968.Ar from_date 969is supplied, all files with a modification or inode change time 970equal to or younger are selected. 971If only a 972.Ar to_date 973is supplied, all files with a modification or inode change time 974equal to or older will be selected. 975When the 976.Ar from_date 977is equal to the 978.Ar to_date , 979only files with a modification or inode change time of exactly that 980time will be selected. 981.Pp 982When 983.Nm 984is in the 985.Em write 986or 987.Em copy 988mode, the optional trailing field 989.Ar [c][m] 990can be used to determine which file time (inode change, file modification or 991both) are used in the comparison. 992If neither is specified, the default is to use file modification time only. 993The 994.Ar m 995specifies the comparison of file modification time (the time when 996the file was last written). 997The 998.Ar c 999specifies the comparison of inode change time (the time when the file 1000inode was last changed; e.g. a change of owner, group, mode, etc). 1001When 1002.Ar c 1003and 1004.Ar m 1005are both specified, then the modification and inode change times are 1006both compared. 1007The inode change time comparison is useful in selecting files whose 1008attributes were recently changed or selecting files which were recently 1009created and had their modification time reset to an older time (as what 1010happens when a file is extracted from an archive and the modification time 1011is preserved). 1012Time comparisons using both file times is useful when 1013.Nm 1014is used to create a time based incremental archive (only files that were 1015changed during a specified time range will be archived). 1016.Pp 1017A time range is made up of six different fields and each field must contain two 1018digits. 1019The format is: 1020.Dl [[[[[cc]yy]mm]dd]hh]mm[\&.ss] 1021Where 1022.Cm cc 1023is the first two digits of the year (the century), 1024.Cm yy 1025is the last two digits of the year, 1026the first 1027.Cm mm 1028is the month (from 01 to 12), 1029.Cm dd 1030is the day of the month (from 01 to 31), 1031.Cm hh 1032is the hour of the day (from 00 to 23), 1033the second 1034.Cm mm 1035is the minute (from 00 to 59), 1036and 1037.Cm ss 1038is the seconds (from 00 to 61). 1039Only the minute field 1040.Cm mm 1041is required; the others will default to the current system values. 1042The 1043.Cm ss 1044field may be added independently of the other fields. 1045If the century is not specified, it defaults to 1900 for 1046years between 69 and 99, or 2000 for years between 0 and 68. 1047Time ranges are relative to the current time, so 1048.Dl Fl T Ar 1234/cm 1049would select all files with a modification or inode change time 1050of 12:34 PM today or later. 1051Multiple 1052.Fl T 1053time range can be supplied and checking stops with the first match. 1054.It Fl U Ar user 1055Select a file based on its 1056.Ar user 1057name, or when starting with a 1058.Cm # , 1059a numeric uid. 1060A '\\' can be used to escape the 1061.Cm # . 1062Multiple 1063.Fl U 1064options may be supplied and checking stops with the first match. 1065.It Fl X 1066When traversing the file hierarchy specified by a pathname, 1067do not descend into directories that have a different device ID. 1068See the 1069.Li st_dev 1070field as described in 1071.Xr stat 2 1072for more information about device ID's. 1073.It Fl Y 1074This option is the same as the 1075.Fl D 1076option, except that the inode change time is checked using the 1077pathname created after all the file name modifications have completed. 1078.It Fl Z 1079This option is the same as the 1080.Fl u 1081option, except that the modification time is checked using the 1082pathname created after all the file name modifications have completed. 1083.It Fl -force-local 1084Do not interpret filenames that contain a `:' as remote files. 1085.It Fl -insecure 1086Normally 1087.Nm 1088ignores filenames that contain `..' as a path component. With this option, 1089files that contain `..' can be processed. 1090.El 1091.Pp 1092The options that operate on the names of files or archive members 1093.Fl ( c , 1094.Fl i , 1095.Fl n , 1096.Fl s , 1097.Fl u , 1098.Fl v , 1099.Fl D , 1100.Fl G , 1101.Fl T , 1102.Fl U , 1103.Fl Y , 1104and 1105.Fl Z ) 1106interact as follows. 1107.Pp 1108When extracting files during a 1109.Em read 1110operation, archive members are 1111.Sq selected , 1112based only on the user specified pattern operands as modified by the 1113.Fl c , 1114.Fl n , 1115.Fl u , 1116.Fl D , 1117.Fl G , 1118.Fl T , 1119.Fl U 1120options. 1121Then any 1122.Fl s 1123and 1124.Fl i 1125options will modify in that order, the names of these selected files. 1126Then the 1127.Fl Y 1128and 1129.Fl Z 1130options will be applied based on the final pathname. 1131Finally the 1132.Fl v 1133option will write the names resulting from these modifications. 1134.Pp 1135When archiving files during a 1136.Em write 1137operation, or copying files during a 1138.Em copy 1139operation, archive members are 1140.Sq selected , 1141based only on the user specified pathnames as modified by the 1142.Fl n , 1143.Fl u , 1144.Fl D , 1145.Fl G , 1146.Fl T , 1147and 1148.Fl U 1149options (the 1150.Fl D 1151option only applies during a copy operation). 1152Then any 1153.Fl s 1154and 1155.Fl i 1156options will modify in that order, the names of these selected files. 1157Then during a 1158.Em copy 1159operation the 1160.Fl Y 1161and the 1162.Fl Z 1163options will be applied based on the final pathname. 1164Finally the 1165.Fl v 1166option will write the names resulting from these modifications. 1167.Pp 1168When one or both of the 1169.Fl u 1170or 1171.Fl D 1172options are specified along with the 1173.Fl n 1174option, a file is not considered selected unless it is newer 1175than the file to which it is compared. 1176.Sh EXAMPLES 1177The command: 1178.Dl pax -w -f /dev/rst0 \&. 1179copies the contents of the current directory to the device 1180.Pa /dev/rst0 . 1181.Pp 1182The command: 1183.Dl pax -v -f filename 1184gives the verbose table of contents for an archive stored in 1185.Pa filename . 1186.Pp 1187The following commands: 1188.Dl mkdir newdir 1189.Dl cd olddir 1190.Dl pax -rw -pp .\ ../newdir 1191will copy the entire 1192.Pa olddir 1193directory hierarchy to 1194.Pa newdir , 1195preserving permissions and access times. 1196.Pp 1197When running as root, one may also wish to preserve file 1198ownership when copying directory trees. 1199This can be done with the following commands: 1200.Dl cd olddir 1201.Dl pax -rw -pe .\ .../newdir 1202which will copy the contents of 1203.Pa olddir 1204into 1205.Pa .../newdir , 1206preserving ownership, permissions and access times. 1207.Pp 1208The command: 1209.Dl pax -r -s ',^//*usr//*,,' -f a.pax 1210reads the archive 1211.Pa a.pax , 1212with all files rooted in ``/usr'' into the archive extracted relative to the 1213current directory. 1214.Pp 1215The command: 1216.Dl pax -rw -i .\ dest_dir 1217can be used to interactively select the files to copy from the current 1218directory to 1219.Pa dest_dir . 1220.Pp 1221The command: 1222.Dl pax -r -pe -U root -G bin -f a.pax 1223will extract all files from the archive 1224.Pa a.pax 1225which are owned by 1226.Em root 1227with group 1228.Em bin 1229and will preserve all file permissions. 1230.Pp 1231The command: 1232.Dl pax -r -w -v -Y -Z home /backup 1233will update (and list) only those files in the destination directory 1234.Pa /backup 1235which are older (less recent inode change or file modification times) than 1236files with the same name found in the source file tree 1237.Pa home . 1238.Sh ERRORS 1239.Nm 1240will exit with one of the following values: 1241.Bl -tag -width 2n 1242.It 0 1243All files were processed successfully. 1244.It 1 1245An error occurred. 1246.El 1247.Pp 1248Whenever 1249.Nm 1250cannot create a file or a link when reading an archive or cannot 1251find a file when writing an archive, or cannot preserve the user ID, 1252group ID, or file mode when the 1253.Fl p 1254option is specified, a diagnostic message is written to 1255.Dv standard error 1256and a non-zero exit status will be returned, but processing will continue. 1257In the case where pax cannot create a link to a file, 1258.Nm 1259will not create a second copy of the file. 1260.Pp 1261If the extraction of a file from an archive is prematurely terminated by 1262a signal or error, 1263.Nm 1264may have only partially extracted a file the user wanted. 1265Additionally, the file modes of extracted files and directories 1266may have incorrect file bits, and the modification and access times may be 1267wrong. 1268.Pp 1269If the creation of an archive is prematurely terminated by a signal or error, 1270.Nm 1271may have only partially created the archive which may violate the specific 1272archive format specification. 1273.Pp 1274If while doing a 1275.Em copy , 1276.Nm 1277detects a file is about to overwrite itself, the file is not copied, 1278a diagnostic message is written to 1279.Dv standard error 1280and when 1281.Nm 1282completes it will exit with a non-zero exit status. 1283.Sh SEE ALSO 1284.Xr cpio 1 , 1285.Xr tar 1 , 1286.Xr symlink 7 , 1287.Xr mtree 8 1288.Sh STANDARDS 1289The 1290.Nm 1291utility is a superset of the 1292.St -p1003.2 1293standard. 1294The options 1295.Fl B , 1296.Fl D , 1297.Fl E , 1298.Fl G , 1299.Fl H , 1300.Fl L , 1301.Fl M , 1302.Fl O , 1303.Fl P , 1304.Fl T , 1305.Fl U , 1306.Fl Y , 1307.Fl Z , 1308the archive formats 1309.Ar bcpio , 1310.Ar sv4cpio , 1311.Ar sv4crc , 1312.Ar tar , 1313and the flawed archive handling during 1314.Ar list 1315and 1316.Ar read 1317operations are extensions to the 1318.Tn POSIX 1319standard. 1320.Sh AUTHORS 1321Keith Muller at the University of California, San Diego. 1322Luke Mewburn implemented 1323.Fl M . 1324