1.\" $NetBSD: pax.1,v 1.59 2010/06/19 11:16:31 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, 2010 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 z 744Use 745.Xr gzip 1 746compression, when reading or writing archive files. 747.It Fl A 748Do not strip leading `/'s from file names. 749.It Fl B Ar bytes 750Limit the number of bytes written to a single archive volume to 751.Ar bytes . 752The 753.Ar bytes 754limit can end with 755.Li m , 756.Li k , 757or 758.Li b 759to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively. 760A pair of 761.Ar bytes 762limits can be separated by 763.Li x 764to indicate a product. 765.Pp 766.Em Warning : 767Only use this option when writing an archive to a device which supports 768an end of file read condition based on last (or largest) write offset 769(such as a regular file or a tape drive). 770The use of this option with a floppy or hard disk is not recommended. 771.It Fl D 772This option is the same as the 773.Fl u 774option, except that the file inode change time is checked instead of the 775file modification time. 776The file inode change time can be used to select files whose inode information 777(e.g. uid, gid, etc.) is newer than a copy of the file in the destination 778.Ar directory . 779.It Fl E Ar limit 780Limit the number of consecutive read faults while trying to read a flawed 781archives to 782.Ar limit . 783With a positive 784.Ar limit , 785.Nm 786will attempt to recover from an archive read error and will 787continue processing starting with the next file stored in the archive. 788A 789.Ar limit 790of 0 will cause 791.Nm 792to stop operation after the first read error is detected on an archive volume. 793A 794.Ar limit 795of 796.Li NONE 797will cause 798.Nm 799to attempt to recover from read errors forever. 800The default 801.Ar limit 802is a small positive number of retries. 803.Pp 804.Em Warning : 805Using this option with 806.Li NONE 807should be used with extreme caution as 808.Nm 809may get stuck in an infinite loop on a very badly flawed archive. 810.It Fl G Ar group 811Select a file based on its 812.Ar group 813name, or when starting with a 814.Cm # , 815a numeric gid. 816A '\e' can be used to escape the 817.Cm # . 818Multiple 819.Fl G 820options may be supplied and checking stops with the first match. 821.It Fl H 822Follow only command line symbolic links while performing a physical file 823system traversal. 824.It Fl L 825Follow all symbolic links to perform a logical file system traversal. 826.It Fl M 827During a 828.Em write 829or 830.Em copy 831operation, treat the list of files on 832.Dv standard input 833as an 834.Xr mtree 8 835.Sq specfile 836specification, and write or copy only those items in the specfile. 837.Pp 838If the file exists in the underlying file system, its permissions and 839modification time will be used unless specifically overridden by the specfile. 840An error will be raised if the type of entry in the specfile conflicts 841with that of an existing file. 842A directory entry that is marked 843.Sq Sy optional 844will not be copied (even though its contents will be). 845.Pp 846Otherwise, the entry will be 847.Sq faked-up , 848and it is necessary to specify at least the following parameters 849in the specfile: 850.Sy type , 851.Sy mode , 852.Sy gname 853or 854.Sy gid , 855and 856.Sy uname 857or 858.Sy uid , 859.Sy device 860(in the case of block or character devices), and 861.Sy link 862(in the case of symbolic links). 863If 864.Sy time 865isn't provided, the current time will be used. 866A 867.Sq faked-up 868entry that is marked 869.Sq Sy optional 870will not be copied. 871.It Fl N Ar dbdir 872Except for lookups for the 873.Fl G 874and 875.Fl U 876options, 877use the user database text file 878.Pa master.passwd 879and group database text file 880.Pa group 881from 882.Ar dbdir , 883rather than using the results from the system's 884.Xr getpwnam 3 885and 886.Xr getgrnam 3 887(and related) library calls. 888.It Fl O 889Force the archive to be one volume. 890If a volume ends prematurely, 891.Nm 892will not prompt for a new volume. 893This option can be useful for 894automated tasks where error recovery cannot be performed by a human. 895.It Fl P 896Do not follow symbolic links, perform a physical file system traversal. 897This is the default mode. 898.It Fl T Ar [from_date][,to_date][/[c][m]] 899Allow files to be selected based on a file modification or inode change 900time falling within a specified time range of 901.Ar from_date 902to 903.Ar to_date 904(the dates are inclusive). 905If only a 906.Ar from_date 907is supplied, all files with a modification or inode change time 908equal to or younger are selected. 909If only a 910.Ar to_date 911is supplied, all files with a modification or inode change time 912equal to or older will be selected. 913When the 914.Ar from_date 915is equal to the 916.Ar to_date , 917only files with a modification or inode change time of exactly that 918time will be selected. 919.Pp 920When 921.Nm 922is in the 923.Em write 924or 925.Em copy 926mode, the optional trailing field 927.Ar [c][m] 928can be used to determine which file time (inode change, file modification or 929both) are used in the comparison. 930If neither is specified, the default is to use file modification time only. 931The 932.Ar m 933specifies the comparison of file modification time (the time when 934the file was last written). 935The 936.Ar c 937specifies the comparison of inode change time (the time when the file 938inode was last changed; e.g. a change of owner, group, mode, etc). 939When 940.Ar c 941and 942.Ar m 943are both specified, then the modification and inode change times are 944both compared. 945The inode change time comparison is useful in selecting files whose 946attributes were recently changed or selecting files which were recently 947created and had their modification time reset to an older time (as what 948happens when a file is extracted from an archive and the modification time 949is preserved). 950Time comparisons using both file times is useful when 951.Nm 952is used to create a time based incremental archive (only files that were 953changed during a specified time range will be archived). 954.Pp 955A time range is made up of six different fields and each field must contain two 956digits. 957The format is: 958.Dl [[[[[cc]yy]mm]dd]hh]mm[\&.ss] 959Where 960.Cm cc 961is the first two digits of the year (the century), 962.Cm yy 963is the last two digits of the year, 964the first 965.Cm mm 966is the month (from 01 to 12), 967.Cm dd 968is the day of the month (from 01 to 31), 969.Cm hh 970is the hour of the day (from 00 to 23), 971the second 972.Cm mm 973is the minute (from 00 to 59), 974and 975.Cm ss 976is the seconds (from 00 to 61). 977Only the minute field 978.Cm mm 979is required; the others will default to the current system values. 980The 981.Cm ss 982field may be added independently of the other fields. 983If the century is not specified, it defaults to 1900 for 984years between 69 and 99, or 2000 for years between 0 and 68. 985Time ranges are relative to the current time, so 986.Dl Fl T Ar 1234/cm 987would select all files with a modification or inode change time 988of 12:34 PM today or later. 989Multiple 990.Fl T 991time range can be supplied and checking stops with the first match. 992.It Fl U Ar user 993Select a file based on its 994.Ar user 995name, or when starting with a 996.Cm # , 997a numeric uid. 998A '\e' can be used to escape the 999.Cm # . 1000Multiple 1001.Fl U 1002options may be supplied and checking stops with the first match. 1003.It Fl V 1004A final summary of archive operations is printed after they have been 1005completed. 1006Some potentially long-running tape operations are noted. 1007.It Fl X 1008When traversing the file hierarchy specified by a pathname, 1009do not descend into directories that have a different device ID. 1010See the 1011.Li st_dev 1012field as described in 1013.Xr stat 2 1014for more information about device ID's. 1015.It Fl Y 1016This option is the same as the 1017.Fl D 1018option, except that the inode change time is checked using the 1019pathname created after all the file name modifications have completed. 1020.It Fl Z 1021This option is the same as the 1022.Fl u 1023option, except that the modification time is checked using the 1024pathname created after all the file name modifications have completed. 1025.It Fl 0 1026Use the nul character instead of \en as the file separator when reading 1027files from standard input. 1028.It Fl Fl force-local 1029Do not interpret filenames that contain a `:' as remote files. 1030.It Fl Fl insecure 1031Normally 1032.Nm 1033ignores filenames that contain 1034.Dq .. 1035as a path component. 1036With this option, 1037files that contain 1038.Dq .. 1039can be processed. 1040.It Fl Fl use-compress-program 1041Use the named program as the program to decompress the input or compress 1042the output. 1043.El 1044.Pp 1045The options that operate on the names of files or archive members 1046.Fl ( c , 1047.Fl i , 1048.Fl n , 1049.Fl s , 1050.Fl u , 1051.Fl v , 1052.Fl D , 1053.Fl G , 1054.Fl T , 1055.Fl U , 1056.Fl Y , 1057and 1058.Fl Z ) 1059interact as follows. 1060.Pp 1061When extracting files during a 1062.Em read 1063operation, archive members are 1064.Sq selected , 1065based only on the user specified pattern operands as modified by the 1066.Fl c , 1067.Fl n , 1068.Fl u , 1069.Fl D , 1070.Fl G , 1071.Fl T , 1072.Fl U 1073options. 1074Then any 1075.Fl s 1076and 1077.Fl i 1078options will modify in that order, the names of these selected files. 1079Then the 1080.Fl Y 1081and 1082.Fl Z 1083options will be applied based on the final pathname. 1084Finally the 1085.Fl v 1086option will write the names resulting from these modifications. 1087.Pp 1088When archiving files during a 1089.Em write 1090operation, or copying files during a 1091.Em copy 1092operation, archive members are 1093.Sq selected , 1094based only on the user specified pathnames as modified by the 1095.Fl n , 1096.Fl u , 1097.Fl D , 1098.Fl G , 1099.Fl T , 1100and 1101.Fl U 1102options (the 1103.Fl D 1104option only applies during a copy operation). 1105Then any 1106.Fl s 1107and 1108.Fl i 1109options will modify in that order, the names of these selected files. 1110Then during a 1111.Em copy 1112operation the 1113.Fl Y 1114and the 1115.Fl Z 1116options will be applied based on the final pathname. 1117Finally the 1118.Fl v 1119option will write the names resulting from these modifications. 1120.Pp 1121When one or both of the 1122.Fl u 1123or 1124.Fl D 1125options are specified along with the 1126.Fl n 1127option, a file is not considered selected unless it is newer 1128than the file to which it is compared. 1129.Sh EXIT STATUS 1130.Nm 1131will exit with one of the following values: 1132.Bl -tag -width 2n 1133.It 0 1134All files were processed successfully. 1135.It 1 1136An error occurred. 1137.El 1138.Pp 1139Whenever 1140.Nm 1141cannot create a file or a link when reading an archive or cannot 1142find a file when writing an archive, or cannot preserve the user ID, 1143group ID, or file mode when the 1144.Fl p 1145option is specified, a diagnostic message is written to 1146.Dv standard error 1147and a non-zero exit status will be returned, but processing will continue. 1148In the case where pax cannot create a link to a file, 1149.Nm 1150will not create a second copy of the file. 1151.Pp 1152If the extraction of a file from an archive is prematurely terminated by 1153a signal or error, 1154.Nm 1155may have only partially extracted a file the user wanted. 1156Additionally, the file modes of extracted files and directories 1157may have incorrect file bits, and the modification and access times may be 1158wrong. 1159.Pp 1160If the creation of an archive is prematurely terminated by a signal or error, 1161.Nm 1162may have only partially created the archive which may violate the specific 1163archive format specification. 1164.Pp 1165If while doing a 1166.Em copy , 1167.Nm 1168detects a file is about to overwrite itself, the file is not copied, 1169a diagnostic message is written to 1170.Dv standard error 1171and when 1172.Nm 1173completes it will exit with a non-zero exit status. 1174.Sh EXAMPLES 1175The command: 1176.Dl pax -w -f /dev/rst0 \&. 1177copies the contents of the current directory to the device 1178.Pa /dev/rst0 . 1179.Pp 1180The command: 1181.Dl pax -v -f filename 1182gives the verbose table of contents for an archive stored in 1183.Pa filename . 1184.Pp 1185The following commands: 1186.Dl mkdir newdir 1187.Dl cd olddir 1188.Dl pax -rw -pp .\ ../newdir 1189will copy the entire 1190.Pa olddir 1191directory hierarchy to 1192.Pa newdir , 1193preserving permissions and access times. 1194.Pp 1195When running as root, one may also wish to preserve file 1196ownership when copying directory trees. 1197This can be done with the following commands: 1198.Dl cd olddir 1199.Dl pax -rw -pe .\ ../newdir 1200which will copy the contents of 1201.Pa olddir 1202into 1203.Pa ../newdir , 1204preserving ownership, permissions and access times. 1205.Pp 1206The command: 1207.Dl pax -r -s ',^//*usr//*,,' -f a.pax 1208reads the archive 1209.Pa a.pax , 1210with all files rooted in ``/usr'' into the archive extracted relative to the 1211current directory. 1212.Pp 1213The command: 1214.Dl pax -rw -i .\ dest_dir 1215can be used to interactively select the files to copy from the current 1216directory to 1217.Pa dest_dir . 1218.Pp 1219The command: 1220.Dl pax -r -pe -U root -G bin -f a.pax 1221will extract all files from the archive 1222.Pa a.pax 1223which are owned by 1224.Em root 1225with group 1226.Em bin 1227and will preserve all file permissions. 1228.Pp 1229The command: 1230.Dl pax -r -w -v -Y -Z home /backup 1231will update (and list) only those files in the destination directory 1232.Pa /backup 1233which are older (less recent inode change or file modification times) than 1234files with the same name found in the source file tree 1235.Pa home . 1236.Sh SEE ALSO 1237.Xr cpio 1 , 1238.Xr tar 1 , 1239.Xr symlink 7 , 1240.Xr mtree 8 1241.Sh STANDARDS 1242The 1243.Nm 1244utility is a superset of the 1245.St -p1003.2 1246standard. 1247The options 1248.Fl B , 1249.Fl D , 1250.Fl E , 1251.Fl G , 1252.Fl H , 1253.Fl L , 1254.Fl M , 1255.Fl O , 1256.Fl P , 1257.Fl T , 1258.Fl U , 1259.Fl Y , 1260.Fl Z , 1261.Fl z , 1262the archive formats 1263.Ar bcpio , 1264.Ar sv4cpio , 1265.Ar sv4crc , 1266.Ar tar , 1267and the flawed archive handling during 1268.Ar list 1269and 1270.Ar read 1271operations are extensions to the 1272.Tn POSIX 1273standard. 1274.Sh AUTHORS 1275Keith Muller at the University of California, San Diego. 1276Luke Mewburn implemented 1277.Fl M . 1278