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